tkassa-mcp

🗄 リポジトリはアーカイブされました

開発は theYahia/WWmcp に移行しました。これは、非西洋圏の API（CIS、MENA、アフリカ、LATAM、東南アジア）向け MCP サーバーのモノレポです。共通コア @theyahia/mcp-core、統一された CI、統一されたリリースパイプラインを備えています。

ここにあったものの最新バージョンは、servers/tkassa/ にあります。

npm パッケージは従来どおり @theyahia/tkassa-mcp です。これまでどおりインストールして使用できます。 このリポジトリは今後更新されません。課題やプルリクエストは WWmcp にお寄せください。

アーカイブ済み — 開発は theYahia/WWmcp に移行しました。 非西洋圏の API 向け MCP サーバーのモノレポです。 このパッケージの最新バージョンは servers/tkassa/ にあります。 npm パッケージ @theyahia/tkassa-mcp に変更はありません。 課題やプルリクエストはそちらにお寄せください。

@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 決済用の QR コードを生成します（ペイロードリンクまたは base64 PNG）
get_sbp_qr_state	SBP QR 決済のステータスを確認します

領収書 - 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"
}

同じ方法（値をソートして連結し、SHA-256 を適用）で Token を計算し、照合して検証します。

注意事項

• ベース 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.

シリーズ：Russian 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