Botwallet MCP

---

MCP クライアントの設定に JSON ブロックを 1 つ追加するだけです。

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

次に、エージェントに「自分用の Botwallet を作成して」と伝えます。

エージェントは botwallet_register を実行し、暗号鍵のシェアをローカルで生成して、入金アドレスを返します。事前のセットアップや API キーの設定は不要です。

そこから、次のように指示できます。

「データレポートの代金として @acme-bot に 5 ドル送って」

金額がガードレールの範囲内であれば、エージェントが署名して送信します。範囲外であれば、人間の所有者に承認を求めます。

「コンサルティングセッションの 25 ドル分の請求書を作成して」

エージェントが支払いリンクを作成します。誰かが支払うと、USDC がウォレットに直接入金されます。

「音声をテキストに変換する API を探して使って」

エージェントは x402 カタログを検索し、有料 API を見つけて利用料を支払い、結果を返します。

署名の仕組み

すべてのウォレットで FROST 2-of-2 閾値署名を使用します。ウォレット作成時に鍵生成セレモニーが行われ、2 つのシェアが生成されます。

• 鍵 1 — エージェントのシェア。ローカルの ~/.botwallet/seeds/ に保存されます。
• 鍵 2 — サーバーのシェア。Botwallet が保持します。

完全な秘密鍵が存在することはありません。すべての取引には両者の共同署名が必要です。エージェントも Botwallet も、単独で資金を移動することはできません。人間の所有者が支出限度額を設定し、ルールの範囲外の取引を承認します。

Botwallet は各取引を準備します。鍵 1 が共同署名する前に、このサーバーが取引をデコードし、ウォレットから USDC だけを送金する場合に限って署名します。送金額は、受取人の関連付けられた（標準の）USDC アカウントへの合意済み金額に、提示された手数料を加えたものまでです。有料 API の手数料はセント単位で提示されるため、最大で提示額より 1 セント多い金額まで許容されます。それ以外の送金は認められません。受取人は、出金、有料 API、および Solana アドレスへの支払いについては、エージェントが指定したアドレスと照合されます。ユーザー名宛ての支払いでは、アドレスは Botwallet の照会結果から取得されるため、エージェントのリクエストと照合されるのは金額と手数料だけです。Agent CLI と署名ページにも同じルールが適用されます。

エージェント自身が指定した金額、受取人、手数料はメモリに保持されるため、送金を開始した MCP サーバープロセスが実行中の間だけ使用されます。所有者の承認が数時間後になるなど、一般的な理由でサーバーを再起動した場合、鍵 1 は取引を Botwallet が記録した金額、受取人、手数料と照合し、固定の上限を超える手数料には決して署名しません。

支払いの呼び出しがタイムアウトした場合や接続が切れた場合、結果には資金が移動した可能性があるかどうかが示されます。OUTCOME_UNKNOWN の場合は、再度支払う前に、check_tool に指定されたツール（通常は botwallet_list_payments または botwallet_get_withdrawal、Botwallet が送金を失敗と表示していても処理が完了している可能性がある場合は botwallet_balance）を使って確認してください。同じ支払いを再試行するには、その idempotency_key を渡してください。

保留中、凍結中、重複する支払い

送信済み、未確認です。 Botwallet は、Solana が支払いまたは出金を確認するまで待機します。ネットワークが時間内に確認できなかった場合、ツールはエラーではなく通常の結果を返し、status: "pending"、sent: true、Solana の署名、エクスプローラーへのリンク、および check_tool を含みます。処理が完了する可能性があるため、エージェントは再度支払ってはいけません。約 1 分後、check_tool のツールに completed または failed が表示されます。

ウォレットの凍結。 所有者は Botwallet のダッシュボードでウォレットを凍結できます。凍結されたウォレットは引き続き入金を受け取れますが、送金はできません。新しい支払い、出金、有料 API 呼び出しはブロックされ、確認処理は署名または送信の前に WALLET_SUSPENDED で停止します。凍結前に承認された送金は保持されます。所有者がウォレットの凍結を解除すると、エージェントは同じ確認ツールと transaction_id を使って処理を完了できます（有料 API の場合は、同じ fetch_id を指定した botwallet_x402_pay_and_fetch を使います）。

リクエストの再試行。 botwallet_pay と botwallet_withdraw は idempotency_key を返します。そのキーを指定してツールを再度呼び出すと、2 回目のリクエストを作成する代わりに、最初のリクエストがどうなったかを返します。キーを指定しない場合は新しいキーが作成されるため、その呼び出しは新たな支払いになります。別の種類のリクエストですでに使用されているキー、または作成中のリクエストに使われているキーを指定すると、IDEMPOTENCY_KEY_CONFLICT が返されます。

インストール

Claude Desktop

Claude Desktop の設定ファイルに追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Claude Code

claude mcp add botwallet -- npx -y @botwallet/mcp

これにより、現在のプロジェクトに追加されます。すべてのプロジェクトで使うには、--scope user を追加します。

claude mcp add --scope user botwallet -- npx -y @botwallet/mcp

ネイティブ Windows（WSL ではない環境）では、npx に cmd /c のラッパーが必要です：claude mcp add botwallet -- cmd /c npx -y @botwallet/mcp。

Cursor

Settings > MCP に移動し、Add new MCP server をクリックして、次を追加します。

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Cline

Cline のサイドバーを開き、MCP Servers、次に Configure をクリックして、次を追加します。

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

その他の MCP クライアント

設定はどのクライアントでも同じです。コマンドとして npx -y @botwallet/mcp を指定します。

グローバルインストール（別の方法）

npm install -g @botwallet/mcp

グローバルにインストールした場合は、コマンドに npx -y @botwallet/mcp ではなく botwallet-mcp を指定してください。

環境変数

変数	デフォルト	用途
BOTWALLET_API_KEY	—	API キー（CLI と同様に、BW_API_KEY も使用できます）。設定すると、使用するウォレットが決まります。読み取り専用の用途にはこれだけで十分ですが、支払い、出金、有料 API 呼び出しには、そのウォレットのキーシェア（Key 1）も ~/.botwallet/seeds/<wallet>.seed に必要です。署名には、このキーを持つ config.json 内のウォレットが使われます。config.json にそのウォレットがない場合は、BOTWALLET_WALLET にシードファイルの名前を設定してください
BOTWALLET_WALLET	—	使用するウォレット（複数ある場合）。この名前のウォレットがない場合、サーバーは起動しません。MCP のみ：CLI では --wallet を使います
BOTWALLET_API_URL	https://api.botwallet.co/v1	API エンドポイント。CLI が読み取るものと同じ変数です。以前のバージョンで使われていた BOTWALLET_BASE_URL も引き続き使用できます。どちらも設定されていない場合は、CLI と同様に ~/.botwallet/config.json の base_url が使われます

すべて省略可能です。サーバーは CLI と共有される ~/.botwallet/config.json を読み取り、残りの設定を判別します。これらの変数を指定しない場合は、デフォルトのウォレットが使われます。ウォレットを登録またはインポートすると、そのウォレットがデフォルトになります。

ツール

8 グループにわたる 36 個のツール。

ウォレット管理

ツール	説明
botwallet_ping	API への接続を確認します
botwallet_register	新しいウォレットを作成します（FROST 鍵生成）
botwallet_info	ウォレットのメタデータとステータスを確認します
botwallet_balance	オンチェーン残高と残りの予算を確認します
botwallet_update_owner	オーナーのメールアドレスを設定します
botwallet_rename	表示名を変更します
botwallet_wallet_list	ローカルのウォレット一覧を表示します
botwallet_wallet_use	アクティブなウォレットを切り替えます

支払い

ツール	説明
botwallet_lookup	受取人が存在するか確認します
botwallet_can_i_afford	支払い前の事前確認を行います
botwallet_pay	支払いを行います（上限内であれば自動署名します）
botwallet_confirm_payment	オーナーの承認後に支払いを完了します
botwallet_list_payments	送金の一覧を表示します
botwallet_cancel_payment	保留中の支払いをキャンセルします

収益化

ツール	説明
botwallet_create_paylink	支払いリクエストまたは請求書を作成します
botwallet_send_paylink	メールまたはボットの受信箱から支払いリンクを送信します
botwallet_get_paylink	支払いリンクのステータスを確認します
botwallet_list_paylinks	自分の支払いリンク一覧を表示します
botwallet_cancel_paylink	保留中の支払いリンクをキャンセルします

入金

ツール	説明
botwallet_get_deposit_address	USDC の入金アドレスを取得します
botwallet_request_funds	人間のオーナーに資金を要求します
botwallet_list_fund_requests	過去の資金リクエスト一覧を表示します

出金

ツール	説明
botwallet_withdraw	USDC を外部の Solana アドレスに出金します
botwallet_confirm_withdrawal	承認後に出金を完了します
botwallet_get_withdrawal	出金のステータスを確認します

x402 有料 API

ツール	説明
botwallet_x402_discover	有料 API を検索します
botwallet_x402_fetch	URL にアクセスして支払い要件を確認します
botwallet_x402_pay_and_fetch	x402 API に支払い、コンテンツを取得します

履歴とガードレール

ツール	説明
botwallet_transactions	全取引の台帳を表示します
botwallet_my_limits	オーナーが設定した支出上限を確認します
botwallet_pending_approvals	承認待ちのアクション一覧を表示します
botwallet_approval_status	特定の承認のステータスを確認します
botwallet_events	ウォレットの通知を確認します

ウォレットの転送

ツール	説明
botwallet_wallet_export	ウォレットを暗号化された .bwlt ファイルにエクスポートします（24 時間以内にインポート可能、最大 5 回）
botwallet_wallet_import	.bwlt ファイルから、新しいローカル名でウォレットをインポートします
botwallet_wallet_backup	オーナーのバックアップ用に Key 1（12 語）を、1 回限りのコードを使って 2 回の呼び出しで表示します

リソース

URI	返される内容
botwallet://status	ウォレットの概要 — 残高、予算、シードファイルのステータス、およびウォレットがまだオーナーに要求されていない場合の要求リンク

アーキテクチャ

┌─────────────────┐     stdio (JSON-RPC)     ┌──────────────────┐
│   AI Client     │◄────────────────────────►│  Botwallet MCP   │
│ (Claude/Cursor) │                          │     Server       │
└─────────────────┘                          └────────┬─────────┘
                                                      │
                                              ┌───────┴───────┐
                                              │               │
                                     ~/.botwallet/     api.botwallet.co
                                     (seeds, config)        (API)
                                                              │
                                                        ┌─────┴─────┐
                                                        │  Solana   │
                                                        │ (mainnet) │
                                                        └───────────┘

サーバーはエージェントのマシン上でローカルに動作します。鍵シェアは ~/.botwallet/seeds/ に保存され、Botwallet に送信されることはありません。サーバーは共同署名のために Botwallet API と通信し、結合された署名を Solana に送信します。

セキュリティ

エージェントは利用上限を回避できません。利用上限はサーバー側で強制されます。自動承認のしきい値を超える取引は、人間の所有者に承認を求めます。システム内のどこにも完全な秘密鍵はありません。

すべてのツールには MCP ツールのアノテーションが付いています。残高、履歴、検索のツールは読み取り専用としてマークされているため、アノテーションに対応したクライアントであれば、確認を求めずに実行できます。送金を行うツール（botwallet_pay、botwallet_withdraw、確認ツール、botwallet_x402_pay_and_fetch）、Key 1 にアクセスするツール（botwallet_wallet_backup、botwallet_wallet_export、botwallet_wallet_import）、または所有者を変更するツールは破壊的操作としてマークされているため、クライアントは実行前に確認を求め続けることができます。サーバー全体を「常に許可」にするより、読み取り専用ツールのみを許可するほうが安全です。

Key 1（エージェントの鍵のシェア）はエージェントのマシンにのみ保存され、Botwallet に送信されることはありません。登録時には、API キーが表示されることなく ~/.botwallet/config.json に保存されます。鍵の情報が明らかになる操作が 2 つあるため、所有者から依頼された場合にのみ使用してください。

• botwallet_wallet_backup は Key 1（12 個の単語）をエージェントに表示し、エージェントが所有者に伝えられるようにします。所有者は出金やウォレットの復元にこの情報を必要とします。単語は AI の会話内に残るため、その会話は機密情報として扱ってください。CLI と同様に、操作には 2 回の呼び出しが必要です。最初の呼び出しで 30 秒間有効なワンタイムコードが返され、2 回目の呼び出しでそのコードを指定すると、単語が表示されます。これにより、誤って Key 1 を明らかにすることを防げますが、意図的に明らかにしようとするエージェントを阻止するものではありません。
• botwallet_wallet_export は Key 1 と API キーを含む .bwlt ファイルを書き出します。このファイルを持つ人は誰でも、24 時間以内にウォレットをインポートできます。

脆弱性の報告については、SECURITY.md をご覧ください。

CLI との相互運用

この MCP サーバーと Botwallet CLI は、同じローカルファイルを使用します。

• 設定：~/.botwallet/config.json
• シード：~/.botwallet/seeds/*.seed
• エクスポート形式：.bwlt（暗号化済みで双方向に使用可能。Key 1 と API キーを含むため、非公開にしてください）

CLI で作成したウォレットは MCP サーバーで使用でき、その逆も可能です。

開発

git clone https://github.com/botwallet-co/mcp.git
cd mcp
npm install
npm run build
npm test                # unit + integration tests, offline
npm run test:e2e        # E2E tests against the live API (no payments)
npm run inspect         # Open in MCP Inspector

ライセンス

Apache 2.0