CoinVello

@coinvello/mcp

非カストディアル型の暗号資産決済プロセッサーである CoinVello API 用の Model Context Protocol サーバーです （KYC 不要、加盟店が鍵を保持、手数料は前払いクレジット、11 のネットワークに対応）。

Claude、Cursor、Windsurf、ChatGPT、または任意の MCP クライアントを使って、連携機能の作成中にチェックアウトセッションの作成、請求書や支払いの確認、Webhook の登録、Webhook 署名の検証、クレジットの管理、テスト支払いのシミュレーションを行えます。

npx -y @coinvello/mcp            # stdio (what every desktop client uses)
npx -y @coinvello/mcp --http 3333  # Streamable HTTP on http://127.0.0.1:3333/mcp

# from a checkout of this repo instead
npm install && npm run build && node dist/index.js

ホステッド（インストール不要）

https://mcp.coinvello.com/mcp では、このサーバーが Streamable HTTP 経由で稼働しています。リクエストごとに独自のキーを Authorization: Bearer cv_test_...（または X-CoinVello-Api-Key、あるいはクエリパラメーターのみを受け付けるクライアントでは api_key 設定）として送信してください。ホステッドサーバーは何も保存せず、テストキーのみを受け付け、キーをログに記録することはありません。npx -y @coinvello/mcp --http --hosted で自分で実行できます。

{ "mcpServers": { "coinvello": { "url": "https://mcp.coinvello.com/mcp", "headers": { "Authorization": "Bearer cv_test_..." } } } }

ドキュメント

AI アシスタント向けのウェブサイトとセットアップ	https://coinvello.com/ai
完全な連携ガイド（LLM 向けに作成された単一ファイル）	https://coinvello.com/llms-full.txt
開発者向けドキュメントと SDK	https://coinvello.com/developers
OpenAPI 3.1 リファレンス	https://coinvello.com/.well-known/openapi.yaml
MCP レジストリ	io.github.CoinVello/coinvello
ソース	https://github.com/CoinVello/coinvello-ai (api/ai/mcp-server)
サポート	[email protected]

設定

変数	必須	意味
COINVELLO_API_KEY	はい	https://coinvello.com/app/settings.php の cv_test_...（Settings -> API keys）。ローカルのモックに対しては、任意の cv_test_ 文字列を使用できます。
COINVELLO_API_BASE	いいえ	デフォルトは https://api.coinvello.com/v1 です。参照用モックサーバーには http://localhost:4242/v1 を使用します。
COINVELLO_ALLOW_LIVE	いいえ	1 に設定しない限り、サーバーは cv_live_ キーでの起動を拒否します。エージェントはテストモードで開発してください。
COINVELLO_API_VERSION	いいえ	CoinVello-Version を固定します（デフォルト：アカウントのバージョン。現在は 2026-10-01）。

クライアントのセットアップ

Claude Desktop

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "cv_test_..." }
    }
  }
}

Claude Code

claude mcp add coinvello -e COINVELLO_API_KEY=cv_test_... -- npx -y @coinvello/mcp

または、プロジェクトのルートにある .mcp.json に記述します（チームと共有し、キーは環境変数経由で指定します）。

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "${COINVELLO_API_KEY}" }
    }
  }
}

Cursor

.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "cv_test_..." }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "cv_test_..." }
    }
  }
}

VS Code（Copilot エージェントモード）

.vscode/mcp.json：

{
  "servers": {
    "coinvello": { "type": "stdio", "command": "npx", "args": ["-y", "@coinvello/mcp"], "env": { "COINVELLO_API_KEY": "cv_test_..." } }
  }
}

リモート／HTTP クライアント（ChatGPT コネクター、ホステッドエージェント）

coinvello-mcp --http 3333 を独自の HTTPS リバースプロキシの背後で実行し、クライアントの接続先を https://your-host/mcp に設定します。HTTP モードはステートレス（リクエストごとにサーバーインスタンスを 1 つ起動）で、デフォルトでは 127.0.0.1 にバインドします（変更するには MCP_HTTP_HOST=0.0.0.0 を指定します）。環境変数のキーを使用するため、認証の背後に配置してください。これは自分のエージェント向けであり、一般公開向けではありません。

ツール

ツール	説明
create_checkout_session	POST /checkout-sessions：ホスト型決済ページを作成します。リダイレクト先の url と invoice_id を返します
get_invoice	GET /invoices/{id}（または GET /checkout-sessions/{cs_id}?expand=invoice）
list_invoices	ステータス、order_id、メールアドレスで絞り込んだ GET /invoices
list_payments	invoice_id、ステータス、chain、tx_hash で絞り込んだ GET /payments
create_wallet	POST /wallets（BTC の場合は xpub、EVM/Solana/Tron の場合はアドレス）。xprv はローカルで拒否します。
list_wallets	GET /wallets
create_webhook	POST /webhooks。whsec_ シークレットを一度だけ返します
verify_webhook_signature	生のボディに対する CoinVello-Signature ヘッダーのローカル HMAC 検証（API 呼び出しなし）
get_credits_balance	GET /credits/balance
list_credit_bundles	GET /credits/bundles
create_credit_purchase	POST /credits/purchases。決済オプションと checkout_url を返します
get_rates	GET /rates
list_assets	GET /assets（チェーンによる絞り込みは任意）
simulate_test_payment	POST /test/simulate_payment（テストキーのみ）
list_records	GET /records：記録簿（決済、手数料、クレジット購入）を発生時点の評価額で表示します。type / asset / chain / invoice / order / tx / 日付 / 通貨で絞り込めます
get_records_summary	GET /records/summary：期間内の売上、受領した市場価値、返金、手数料、受取純額を表示します。グループ化も指定できます
create_export	POST /exports：記録または任意のデータセットの CSV、Excel、JSON ファイルを作成します（QuickBooks、Xero、Koinly、CoinTracker、CoinLedger のプリセット）。download_url を含むエクスポートを返します
get_export	GET /exports/{id}：ステータスが ready になるまでポーリングし、file.sha256 と download_url を読み取ります

すべてのツールは未加工の API JSON を返します（structuredContent としても返します）。API エラーは、http_status、CoinVello の error エンベロープ（type、code、message、request_id）、および hint を含むツールエラーとして返されます。

リソース

URI	内容
coinvello://docs/llms-full.txt	統合ガイド全文（認証、チェックアウト、リダイレクト、Webhook 検証、ポーリング、クレジット、エラー、curl/Node/Python/PHP の例）を収録した単一ファイル
coinvello://docs/llms.txt	llms.txt の簡易インデックス
coinvello://openapi.yaml	OpenAPI 3.1 仕様

ドキュメントはビルド時にバンドルされます。見つからない場合は coinvello.com から取得されます。

プロンプト

nextjs、express、fastapi、flask、django、 laravel、rails、sinatra、go、woocommerce、shopify、generic 向けの integrate-coinvello-into-<framework> と、 自由形式の framework 引数を指定できる integrate-coinvello-into-framework があります。任意の引数： currency、assets。各プロンプトでは、エージェントにガイドリソースの読み込み、チェックアウトルートの追加、署名検証と event.id による重複排除を行う生ボディの Webhook ルートの追加、および simulate_test_payment によるエンドツーエンドの検証を指示します。

一般的なエージェントセッション

1. list_assets -> 加盟店が受け付ける資産を選びます。
2. アプリの /webhooks/coinvello URL を指定して create_webhook を実行 -> シークレットを環境ファイルに保存します。
3. コードを記述します（integrate-coinvello-into-* プロンプトまたは api/ai/cookbook を参照）。
4. create_checkout_session -> 十分な承認数を指定して、invoice_id に対して simulate_test_payment を実行します。
5. get_invoice でステータスが paid と表示されます。アプリの Webhook ハンドラーには、署名付きの実イベントが呼び出されました。
6. 配信を拒否するハンドラーのデバッグには verify_webhook_signature を使用します。
7. 帳簿処理：list_records（テストモードでは include_simulated: true を指定） -> 期間を指定して get_records_summary -> create_export（format: "xlsx"） -> ready になるまで get_export を実行 -> download_url をダウンロードし、file.sha256 を確認します。

開発

npm install
npm run build          # copies docs into dist/docs and compiles TypeScript
npm test               # smoke test against the mock: needs api/reference-server running on :4242
npm run dev            # tsx src/index.ts (stdio)

スモークテスト：cd api/reference-server && npm install && npm start を実行し、その後ここで COINVELLO_API_BASE=http://localhost:4242/v1 npm test を実行します。18 個すべてのツール、3 つの リソース、プロンプトをテストし、モックの webhook シンクで取得した実際の署名付き配信を検証し、 xprv ガードを確認します。モックはウォレットの CRUD を実装していないため、create_wallet / list_wallets はそこで正常な 404 ツールエラーを返すことが想定されています。

セキュリティに関する注意事項

• エージェントがコードを書いている間は、サーバーでテストキーを使用してください。COINVELLO_ALLOW_LIVE=1 は意図的に有効化するオプションです。
• サーバーは API キーや webhook シークレットをログに記録しません。ツールの出力には create_webhook の secret が含まれます。これは API がその値を返す唯一のタイミングだからです。
• create_wallet は、拡張秘密鍵と思われる値がマシンの外部に送信される前に拒否します。
• ここでは資金は移動しません。CoinVello はノンカストディアルであり、API に「送金」操作はありません。

ライセンス：MIT。ソース：https://github.com/CoinVello/coinvello-ai （ミラー）。問題の報告：https://github.com/CoinVello/coinvello-ai/issues または [email protected]