tkassa-mcp

🗄 仓库已归档

开发工作已迁移至 theYahia/WWmcp——一个面向非西方 API 的 MCP 服务单体仓库，涵盖独联体、MENA、非洲、LATAM、东南亚。包含通用核心 @theyahia/mcp-core、统一 CI 和统一发布流水线。

此处原有内容的最新版本：servers/tkassa/

npm 包保持不变——@theyahia/tkassa-mcp，安装和运行方式与以前相同。 此处不再进行任何更新。请在 WWmcp 中提交问题和 pull request。

**已归档——开发工作已迁移至 theYahia/WWmcp，**这是一个面向非西方 API 的 MCP 服务单体仓库。 此软件包的当前版本现位于 servers/tkassa/。 npm 包 @theyahia/tkassa-mcp 保持不变。 请在那里提交问题和 pull request。

@theyahia/tkassa-mcp

适用于 T-Kassa（T-Bank/Tinkoff）支付 API 的 MCP 服务。**16 个工具：**支付、退款、周期性扣款、客户管理、已保存的银行卡、SBP（快速支付）、收据（54-FZ）、T-Invest 投资组合。

这是由 @theYahia 创建的 Russian API MCP 系列（50 个服务）的一部分。

快速开始

Claude Desktop

{
  "mcpServers": {
    "tkassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/tkassa-mcp"],
      "env": {
        "TKASSA_TERMINAL_KEY": "your-terminal-key",
        "TKASSA_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add tkassa -e TKASSA_TERMINAL_KEY=your-key -e TKASSA_PASSWORD=your-password -- npx -y @theyahia/tkassa-mcp

Cursor / Windsurf

{
  "tkassa": {
    "command": "npx",
    "args": ["-y", "@theyahia/tkassa-mcp"],
    "env": {
      "TKASSA_TERMINAL_KEY": "your-terminal-key",
      "TKASSA_PASSWORD": "your-password"
    }
  }
}

环境变量

变量	必填	说明
TKASSA_TERMINAL_KEY	是	终端密钥（Dashboard -> Shops -> Terminals）
TKASSA_PASSWORD	是	终端密码（用于 SHA-256 令牌签名）
TINKOFF_INVEST_TOKEN	否	T-Invest API 令牌（用于工具 15–16）。在 T-Invest 应用中获取：Settings → OpenAPI Token

在 T-Kassa Dashboard 获取测试凭证。

工具（16 个）

支付（5 个）

工具	说明
init_payment	创建支付。返回 PaymentURL。支持单阶段/双阶段支付、收据（54-FZ）、周期性扣款、DATA 字段
get_payment_state	根据 PaymentId 获取支付状态（NEW、AUTHORIZED、CONFIRMED、REVERSED、REFUNDED、REJECTED）
confirm_payment	确认双阶段支付。支持部分确认
cancel_payment	取消支付（确认前或确认后）。支持部分取消
charge_payment	使用已保存银行卡中的 RebillId 发起周期性扣款

退款（1 个）

工具	说明
refund_payment	全额或部分退款。支付状态必须为 CONFIRMED

客户与银行卡（5 个）

工具	说明
add_customer	注册客户，以便保存银行卡并进行周期性扣款
get_customer	根据 CustomerKey 获取客户数据（Email、Phone）
remove_customer	移除客户及其所有已保存的银行卡
get_card_list	列出已保存的银行卡（CardId、Pan、ExpDate、RebillId）
remove_card	根据 CardId 移除已保存的银行卡

SBP - 快速支付（2 个）

工具	说明
create_sbp_qr	生成 SBP 支付二维码（链接载荷或 base64 PNG）
get_sbp_qr_state	查询 SBP 二维码支付状态

收据 - 54-FZ（1 个）

工具	说明
send_closing_receipt	发送结账收据，包含用于满足税务合规要求的 Items（Name、Price、Quantity、Tax）

T-Invest（2）

需要 TINKOFF_INVEST_TOKEN。如果未设置，这些工具会返回说明性错误。

工具	描述
get_invest_portfolio	获取投资组合：股票、债券、ETF、当前价值和盈亏
find_instrument	按股票代码、ISIN 或公司名称搜索金融工具。返回 FIGI 键

身份验证

每个请求都使用 SHA-256 签名：

Token = SHA-256(concat(sorted values of {Password, TerminalKey, ...params}))

只有标量值参与签名。嵌套对象（Receipt、DATA）不参与。此过程会自动处理。

HTTP 传输

HTTP_PORT=3000 npx @theyahia/tkassa-mcp
# or
npx @theyahia/tkassa-mcp --http 3000

端点：POST /mcp（JSON-RPC）、GET /health（状态）。

技能

• skill-create-payment -- 创建付款并获取付款 URL
• skill-payment-status -- 按 PaymentId 查询付款状态

Webhook 通知

付款状态发生变化时，T-Kassa 会向你的 notification_url（在 init_payment 中设置）发送 POST 通知：

{
  "TerminalKey": "your-key",
  "OrderId": "your-order-id",
  "Success": true,
  "Status": "CONFIRMED",
  "PaymentId": 123456789,
  "ErrorCode": "0",
  "Amount": 10000,
  "RebillId": 987654321,
  "CardId": 12345,
  "Pan": "430000******0777",
  "ExpDate": "1230",
  "Token": "sha256-signature"
}

通过以相同方式计算 Token（拼接排序后的值 + SHA-256）并进行比较来验证。

备注

• 基础 URL：https://securepay.tinkoff.ru/v2/
• 金额在内部以戈比为单位（服务端会自动转换为卢布）
• 在 429/5xx 错误时自动进行指数退避重试
• API 文档：https://www.tbank.ru/kassa/dev/payments/

示例提示词

创建带有收据的付款：

Create a payment for 1500 rubles, order "order-42", with a receipt: 1x "Premium subscription" at 1500 RUB, VAT 20%, tax system USN income. Send receipt to [email protected].

设置定期付款：

Register customer "cust-123" with email [email protected], then create a recurring payment for 990 rubles on order "sub-monthly-1".

退款并查询状态：

Refund 500 rubles from payment 777888999, then check its current status.

系列：俄罗斯 API MCP

MCP	状态	描述
@metarebalance/dadata-mcp	就绪	地址、公司、银行、电话号码
@theyahia/cbr-mcp	就绪	汇率、关键利率
@theyahia/yookassa-mcp	就绪	付款、退款、54-FZ 收据
@theyahia/tkassa-mcp	v2.1	16 个工具 -- 付款、退款、定期付款、SBP、收据、T-Invest
...	即将推出	+46 个服务 -- 完整列表

许可证

MIT

---

Telegram： @vhodvai