Jami

jami-mcp

JamiDev（Jamiのクリエイターへの支払いを実現するSDK）向けの、公式Model Context Protocolサーバーです。Claude、Cursor、VS Code、Codexなど、あらゆるMCPクライアントに接続すると、エージェントがETB決済を作成し、決済完了を監視し、注文を照合し、支払いのプレビューと送信を行い、Webhookをデバッグし、連携コードの作成中にJamiのドキュメントを参照できます。決済処理はArifPayが行います。

公式のjami-sdkを基盤としているため、各ツールはSDKおよびREST APIとまったく同じように動作します。

npx -y jami-mcp

クイックスタート

1. トークンを取得します：Jamiダッシュボード → JamiDev → Developer → API Tokens。まずはサンドボックス組織を使いましょう。そのjamidev_test_…トークンでは実際の資金は動きません。
2. トークンをJAMI_TOKENとして設定し、以下の手順でMCPサーバーをクライアントに追加します。
3. 次のように依頼します：「Telebirrで、注文#1042の代金1,237ビルを[email protected]に請求してください。電話番号は251900000001です。決済が完了するまで待ってください。」

まだトークンをお持ちでなくても、MCPサーバーは動作します。ドキュメント、出金見積もり、Webhookの各ツールはトークンなしで使えるため、すぐに開発を始められます。

Claude Code

claude mcp add jami -e JAMI_TOKEN=jamidev_test_xxx -- npx -y jami-mcp

Claude Desktop · Cursor · Windsurf

claude_desktop_config.json、~/.cursor/mcp.json、または~/.codeium/windsurf/mcp_config.jsonに追加します：

{
  "mcpServers": {
    "jami": {
      "command": "npx",
      "args": ["-y", "jami-mcp"],
      "env": { "JAMI_TOKEN": "jamidev_test_xxx" }
    }
  }
}

VS Code

.vscode/mcp.json — VS Codeがトークンの入力を求め、安全に保存します：

{
  "inputs": [
    { "type": "promptString", "id": "jami-token", "description": "JamiDev API token", "password": true }
  ],
  "servers": {
    "jami": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jami-mcp"],
      "env": { "JAMI_TOKEN": "${input:jami-token}" }
    }
  }
}

Codex

~/.codex/config.toml：

[mcp_servers.jami]
command = "npx"
args = ["-y", "jami-mcp"]
env = { JAMI_TOKEN = "jamidev_test_xxx" }

ツール

ツール	機能	トークンが必要
jami_create_checkout	商品（p_…トークンまたはID）または任意の金額（amount_minor + description）を請求します。gatewayを指定すると、購入者の電話に支払いリクエストを送信します。指定しない場合は、送信用のJami決済リンクを返します。	✓
jami_create_product · jami_update_product	商品を作成または編集します。各商品について、公開ページとp_…トークンが返されます。	✓
jami_get_product · jami_list_products	商品カタログを参照します。	✓
jami_get_checkout_status	セッションの状態を一度確認し、期限切れの場合は失敗理由も返します。	✓
jami_wait_for_checkout	進捗を更新しながら、購入者の手続き完了を待ちます。タイムアウト時にopenを返すため、処理がいつまでも止まることはありません。	✓
jami_list_orders	新しい順の注文一覧を返します。ページネーションに対応し、ステータスで絞り込めます。	✓
jami_get_balance	出金可能な収益と、組織が出金できるかどうかを返します。	✓
jami_quote_withdrawal	指定金額に対する手数料、税金、差引額のほか、自動支払いと上限のチェック結果を返します。オフラインで動作します。	—
jami_create_withdrawal	Telebirr、M-Pesa、またはCBE Birrに支払います。明示的な有効化が必要（「安全性」を参照）。	✓
jami_get_withdrawal · jami_list_withdrawals	支払い状況を追跡します。	✓
jami_verify_webhook	受信したWebhookの署名と、失敗した場合の理由を確認します。	—
jami_create_test_webhook	正しく署名されたテストイベントを作成し、オプションでローカルのハンドラーにPOSTします。	—
jami_search_docs · jami_read_doc	dev.jami.bioで公開されている最新のドキュメントを検索して読みます。	—

すべてのツールは、読みやすいMarkdownの概要と、型付きのstructuredContentを返します。生のペイロードを取得するには、response_format: "json"を指定してください。金額は常に整数のサンティムで表し、金額を扱うパラメーター名はすべて_minorで終わります：amount_minor: 15000 = 150.00 ETB。

プロンプト： integrate_jami（使用するスタックで連携全体を構築）、go_live_checklist、debug_payment。リソース： jami://reference — 手数料、上限、サンドボックス用の番号、失敗コード、Webhookのルールを1ページにまとめています。

安全性

デフォルト設定では、エージェントが誤って送金できないようになっています。

• 出金は無効です。サーバーを --enable-withdrawals（または JAMI_ENABLE_WITHDRAWALS=true）を指定して起動するまで無効のままです。有効にすると、エリシテーションに対応したクライアントでは、各支払いの確認を求められます。また、すべての支払いに idempotency_key が必要なため、再試行しても二重に支払われることはありません。サンドボックストークンは、リクエストを行う前に拒否されます。
• --read-only を指定すると、データを読み取るツールのみが登録されます。レポート作成用のエージェントに使用してください。
• ライブモードは通知されます。 jamidev_live_ トークンを使用すると、チェックアウトで実際の購入者に請求が発生するため、先に確認するようサーバーがエージェントに伝えます。
• トークンは環境内に保持されます。ツールの出力に表示されることはありません。

オプション

--http                 Streamable HTTP on POST /mcp instead of stdio
--port <n>             HTTP port (default 3333)
--host <addr>          HTTP bind address (default 127.0.0.1)
--read-only            Only read tools
--enable-withdrawals   Register jami_create_withdrawal
--base-url <url>       Override the API base (default https://jami.bio/api/jamidev)
--docs-url <url>       Override the docs origin (default https://dev.jami.bio)

環境変数	目的
JAMI_TOKEN	jamidev_test_… または jamidev_live_…
JAMI_WEBHOOK_SECRET	Webhook ツールのデフォルトのシークレット
JAMI_READ_ONLY, JAMI_ENABLE_WITHDRAWALS	フラグと同じ

リモート（HTTP）モード

npx -y jami-mcp --http --port 3333
# → http://127.0.0.1:3333/mcp   (health check: /healthz)

HTTP サーバーはステートレスなので、1 つのプロセスを任意の数のクライアントで共有できます。 JAMI_TOKEN が設定されていない場合、各リクエストは独自の Authorization: Bearer jamidev_… ヘッダーで認証されるため、1 つのデプロイメントをチーム間で安全に共有できます。ループバックでは、サーバーは不正な Host ヘッダーを拒否します（DNS リバインディング対策）。HTTP モードでは、jami_create_test_webhook はリクエストを送信せず、署名済みのペイロードと curl コマンドを返すだけです。

埋め込み

import { createJamiServer } from 'jami-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createJamiServer({ token: process.env.JAMI_TOKEN, docsUrl: 'https://dev.jami.bio', readOnly: true, withdrawals: false });
await server.connect(new StdioServerTransport());

開発

npm install
npm test          # in-memory MCP client against a mocked API
npm run build
npm run inspect   # opens the MCP Inspector on dist/index.js

詳細なガイド：dev.jami.bio/docs/mcp · サポート：[email protected]

MIT © Jami