English Français العربية

io.github.theYahia/tkassa-mcp

السجل الرسمي مؤرشف المالية والمدفوعات

MCP server for T-Kassa (T-Bank/Tinkoff) payment API — payments, refunds. 5 tools. First MCP for T-K

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @theyahia/tkassa-mcp
Claude Code 
claude mcp add tkassa-mcp -e 'TKASSA_TERMINAL_KEY=<your tkassa_terminal_key>' -- npx -y @theyahia/tkassa-mcp@1.0.0
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "tkassa-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@theyahia/tkassa-mcp@1.0.0"
            ],
            "env": {
                "TKASSA_TERMINAL_KEY": "<your tkassa_terminal_key>"
            }
        }
    }
}

متغيرات البيئة

  • TKASSA_TERMINAL_KEY إلزامي سري API key for the service

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. 🗄 Репозиторий заархивирован
  2. @theyahia/tkassa-mcp
  3. Quick Start
  4. Environment Variables
  5. Tools (16)
  6. Auth
  7. HTTP Transport
  8. Skills
  9. Webhook Notifications
  10. Notes
  11. Demo Prompts
  12. Series: Russian API MCP
  13. License

🗄 Репозиторий заархивирован

Разработка переехала в theYahia/WWmcp — монорепозиторий MCP-серверов для незападных API: СНГ, MENA, Африка, LATAM, Юго-Восточная Азия. Общее ядро @theyahia/mcp-core, единый CI, единый релизный конвейер.

Актуальная версия того, что лежало здесь: servers/tkassa/

Пакет в npm прежний — @theyahia/tkassa-mcp, ставится и работает как раньше. Здесь больше ничего не обновляется. Задачи и pull request'ы — в WWmcp.

Archived — development moved to theYahia/WWmcp, a monorepo of MCP servers for non-Western APIs. The current version of this package now lives at servers/tkassa/. The npm package @theyahia/tkassa-mcp is unchanged. Please open issues and pull requests there.

@theyahia/tkassa-mcp

MCP server for T-Kassa (T-Bank/Tinkoff) payment API. 16 tools: payments, refunds, recurring charges, customer management, saved cards, SBP (Fast Payments), receipts (54-FZ), T-Invest portfolio.

Part of the Russian API MCP series (50 servers) by @theYahia.

Quick Start

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"
    }
  }
}

Environment Variables

VariableRequiredDescription
TKASSA_TERMINAL_KEYYesTerminal key (Dashboard -> Shops -> Terminals)
TKASSA_PASSWORDYesTerminal password (used for SHA-256 token signing)
TINKOFF_INVEST_TOKENNoT-Invest API token (for tools 15–16). Get in T-Invest app: Settings → OpenAPI Token

Get test credentials at T-Kassa Dashboard.

Tools (16)

Payments (5)
ToolDescription
init_paymentCreate a payment. Returns PaymentURL. Supports one-step/two-step, receipts (54-FZ), recurring, DATA fields
get_payment_stateGet payment status by PaymentId (NEW, AUTHORIZED, CONFIRMED, REVERSED, REFUNDED, REJECTED)
confirm_paymentConfirm a two-step payment. Supports partial confirmation
cancel_paymentCancel a payment (before or after confirmation). Supports partial cancellation
charge_paymentCharge a recurring payment using RebillId from a saved card
Refunds (1)
ToolDescription
refund_paymentFull or partial refund. Payment must be in CONFIRMED status
Customers & Cards (5)
ToolDescription
add_customerRegister a customer for saving cards and recurring payments
get_customerGet customer data (Email, Phone) by CustomerKey
remove_customerRemove a customer and all saved cards
get_card_listList saved cards (CardId, Pan, ExpDate, RebillId)
remove_cardRemove a saved card by CardId
SBP - Fast Payments (2)
ToolDescription
create_sbp_qrGenerate QR code for SBP payment (payload link or base64 PNG)
get_sbp_qr_stateCheck SBP QR payment status
Receipts - 54-FZ (1)
ToolDescription
send_closing_receiptSend a closing receipt with Items (Name, Price, Quantity, Tax) for fiscal compliance
T-Invest (2)

Requires TINKOFF_INVEST_TOKEN. If not set, these tools return a descriptive error.

ToolDescription
get_invest_portfolioGet investment portfolio: stocks, bonds, ETFs, current value and P&L
find_instrumentSearch instrument by ticker, ISIN, or company name. Returns FIGI key

Auth

Every request is signed with SHA-256:

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

Only scalar values participate in signing. Nested objects (Receipt, DATA) are excluded. Handled automatically.

HTTP Transport

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

Endpoints: POST /mcp (JSON-RPC), GET /health (status).

Skills

  • skill-create-payment -- create a payment and get a payment URL
  • skill-payment-status -- check payment status by PaymentId

Webhook Notifications

T-Kassa sends POST notifications to your notification_url (set in init_payment) when payment status changes:

{
  "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"
}

Verify by computing the Token the same way (sorted values concat + SHA-256) and comparing.

Notes

  • Base URL: https://securepay.tinkoff.ru/v2/
  • Amounts are in kopecks internally (server converts rubles automatically)
  • Automatic retry with exponential backoff on 429/5xx
  • API docs: https://www.tbank.ru/kassa/dev/payments/

Demo Prompts

Create a payment with receipt:

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 user@example.com.

Set up recurring payments:

Register customer "cust-123" with email user@example.com, then create a recurring payment for 990 rubles on order "sub-monthly-1".

Refund and check status:

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

Series: Russian API MCP

MCPStatusDescription
@metarebalance/dadata-mcpreadyAddresses, companies, banks, phones
@theyahia/cbr-mcpreadyExchange rates, key rate
@theyahia/yookassa-mcpreadyPayments, refunds, receipts 54-FZ
@theyahia/tkassa-mcpv2.116 tools -- payments, refunds, recurring, SBP, receipts, T-Invest
...soon+46 servers -- full list

License

MIT

Telegram: @vhodvai

الأسئلة الشائعة

ما هو io.github.theYahia/tkassa-mcp؟

MCP server for T-Kassa (T-Bank/Tinkoff) payment API — payments, refunds. 5 tools. First MCP for T-K

كيف أثبّت io.github.theYahia/tkassa-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add tkassa-mcp -e 'TKASSA_TERMINAL_KEY=<your tkassa_terminal_key>' -- npx -y @theyahia/tkassa-mcp@1.0.0. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.theYahia/tkassa-mcp إلى مفتاح API؟

نعم. يتطلب TKASSA_TERMINAL_KEY، وتضبطها في إعداداته.

هل io.github.theYahia/tkassa-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.theYahia/tkassa-mcp؟

ينشره theYahia. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.