monad-mcp

monad-mcp

Monadブロックチェーン向けのMCPサーバーです。Monad上の残高、送金、スワップ、DeFiを利用するためのエージェントのゲートウェイです。署名はエージェントではなく、Privyの埋め込みウォレットが処理します。

シンプルな構成（保存済みリクエスト＋承認URL＋スキルプラグイン）を基盤とし、Monadのメインネット143／テストネット10143で、ウォレットプロバイダーとしてPrivyを使用します。

🌐 ランディングページ＋読み取り専用のライブデモ： pareen.github.io/monad-mcp — ブラウザーでMonadの実際の残高を照会できます。エージェントに表示される内容そのものです。

🔌 インストールもターミナルも不要です。接続するには、 Claude DesktopまたはChatGPTでカスタムコネクターを追加し、このURLを貼り付けます。

https://monad-mcp.fly.dev/mcp

セットアップはこれだけです。読み取りツール（残高、価格、ポートフォリオ、トークンチェック）はすぐに使えます。各アプリの手順については、docs/connect-claude.mdをご覧ください。

ターミナルを使う場合は、Claude Codeで次の1行を実行します。

claude mcp add --transport http monad https://monad-mcp.fly.dev/mcp   # hosted
claude mcp add monad -- npx -y monad-mcp                              # or run it locally

ホストされたエンドポイントは分割モードで動作します。読み取りツールは公開されているため（URLを貼るだけでログイン不要。安全に共有できます）、書き込みツールはPrivyへのサインインが必要で、認証するまではauth_requiredを返します。ホスト上のサインイン経路は接続済みですが、エンドツーエンドの検証がまだ完了していません。そのため、トランザクションについては、ご自身のPrivy署名付きインスタンスを使用する方法が検証済みの手順です。docs/connect-claude.md、よくあるセキュリティ／セットアップの質問についてはdocs/FAQ.md、docs/DEPLOY.mdをご覧ください。

🧭 Monad ≠ Ethereum： このサーバーは、Monad特有の仕様（128 KBのコントラクト、gas_limitによる課金、投機的なlatest、eth_getLogsの上限、FastLane／MEV）についてのエージェント向けガイダンスを、monad://guide/*のMCPリソースとして提供します。docs/building-on-monad.mdをご覧ください。

同梱内容

コアツール（任意のアドレスで動作し、認証が必要なのは記載がある場合のみです）：

ツール	認証	機能
create_user	なし	Privy ユーザーと Monad 対応の埋め込みウォレットを作成します。セルフサービスでオンボーディングできます。
whoami	必須	ユーザー ID、ウォレットアドレス、アクティブなセッションキーの許可を返します。
get_address	必須	接続中のウォレットのアドレスを返します。
get_balance	任意	ネイティブ MON の残高を返します。0x アドレスまたは .nad 名を指定できます。
get_token_balance	任意	小数桁数とシンボルを含む ERC-20 残高を返します。.nad 名を指定できます。
get_portfolio	任意	DexScreener 経由で、すべての正規トークンの残高と USD 価格を返します。.nad 名を指定できます。
get_transaction_history	任意	RPC ログスキャンとエクスプローラー URL を使用して、最近の ERC-20 送金を返します。.nad 名を指定できます。
get_tx_receipt	なし	トランザクションハッシュに対応するレシートを返します。
simulate_transaction	任意	呼び出しをドライラン（eth_call）し、戻りデータまたはリバート理由を返します。
check_token	なし	リスクヒューリスティックを確認します。正規リストへの登録、バイトコード、DEX 流動性、ペアの経過期間を確認します。
resolve_token	なし	シンボル／名前／エイリアスからトークンアドレスを解決します（正規リストと DexScreener のフォールバックを使用）。
get_token_price	なし	Monad 上で最も流動性の高い DexScreener ペアから USD 価格を取得します。
list_canonical_tokens	なし	Monad の既知のトークンをまとめた組み込みリストを返します。
resolve_name	なし	Nad Name Service（nad.domains）を使用し、.nad 名からアドレスへ、またアドレスからプライマリ .nad 名へ解決します。
read_contract	なし	ABI をインラインで指定して、任意の Monad コントラクトの view／pure 関数を呼び出します。
decode_return_data	なし	ABI に基づいて 16 進数の戻りデータをデコードします。
bridge_quote	任意	任意のチェーンから Monad への LiFi アグリゲーター見積もりを取得します。
poll_request	なし	保留中の承認リクエストのステータスを返します。
transfer	必須	ネイティブ MON または ERC-20 を送金します。宛先には 0x アドレスまたは .nad 名を指定できます。セッション許可があれば自動実行し、なければ承認 URL を返します。
write_contract	必須	任意のコントラクトにトランザクションを送信します（view 以外の任意の関数）。
pay_for_service	必須	x402（HTTP 402）— Privy 経由で EIP-3009 USDC 認証に署名し、X-PAYMENT を付けて再試行します。
bridge_execute	必須	bridge_quote が返した送信元チェーンのトランザクションを送信します（送信元が Monad の場合のみ）。
grant_session_key	必須	1 トランザクションごとの承認なしで最大 N MON を使用できるよう、エージェントに許可を与えます。
list_session_keys	必須	アクティブな許可と最近の許可を表示します。
revoke_session_key	必須	許可を直ちに取り消します。

スキルプラグイン（追加式です。src/plugins/ に独自のプラグインを配置できます）：

• Uniswap（uniswap_quote、uniswap_swap、approve_erc20）— Uniswap v3 での完全指定入力によるシングルホップスワップ（テストネットとメインネット）。
• Kintsu（kintsu_stake、kintsu_request_unstake、kintsu_claim_unstake、kintsu_position）— Kintsu の ERC-7535 ボールトを介した、MON から sMON へのリキッドステーキング。アンステークは 2 段階で、バッチ処理を行います。
• FastLane（fastlane_stake、fastlane_unstake、fastlane_position）— FastLane の shMONAD ERC-4626 ボールトを介した、MON から shMON へのリキッドステーキング。ネイティブトークンの入金に対応し、同期的に償還されます（エポック待ちなし）。shMON はステーキング報酬と MEV 報酬を獲得し続けます。
• Morpho（morpho_supply、morpho_withdraw、morpho_borrow、morpho_repay、morpho_position、morpho_market）— Morpho Blue のシングルトンでの貸し借り。呼び出し元は MarketParams をインラインで渡し、プラグインがマーケット ID を導出します。
• Kuru（kuru_best_bid_ask、kuru_market_params、kuru_place_limit、kuru_cancel_orders、kuru_market_swap）— 完全オンチェーンの CLOB。既知のメインネットマーケット（MON/USDC、MON/AUSD、WETH/USDC）が付属し、新しいマーケットには生のアドレスを指定できます。

すべてのプラグインの書き込みツールは、適用可能なセッションキー許可を介して自動的にルーティングされます（下記の「セッションキー」を参照）。該当する許可がない場合は、承認 URL を返します。

メインネット専用プラグイン（Kintsu／FastLane／Morpho／Kuru）は、MONAD_DEFAULT_NETWORK=testnet の場合、起動時にスキップされます。ツールごとに network: "mainnet" を指定して上書きできます。

クイックスタート

1. インストールと設定

git clone https://github.com/you/monad-mcp.git
cd monad-mcp
npm install
cp .env.example .env

.env を編集します。書き込みツールを使って何かを行うための最低限の設定は次のとおりです。

PRIVY_APP_ID=clxxxxxxxxxxx          # from https://dashboard.privy.io
PRIVY_APP_SECRET=...                # from the same place
PRIVY_VERIFICATION_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"  # optional but recommended

# Where this server is reachable from a browser (used in approval URLs).
PUBLIC_BASE_URL=http://localhost:8787
PORT=8787

# Which Monad network to default to when a tool call omits `network`.
MONAD_DEFAULT_NETWORK=testnet

Uniswap プラグインでは、コントラクトアドレスを指定してください（使用する前に、Monad の正規の Uniswap デプロイと照合してください）。

UNISWAP_MAINNET_QUOTER_V2=0x...
UNISWAP_MAINNET_SWAP_ROUTER_02=0x...
UNISWAP_TESTNET_QUOTER_V2=0x...
UNISWAP_TESTNET_SWAP_ROUTER_02=0x...

2. Privy アプリの設定

Privy ダッシュボードで次の操作を行います。

1. アプリを作成します。「Wallets」で埋め込みウォレットを有効にします。
2. 「Networks」で Monad メインネット（chainId 143）および／またはテストネット（chainId 10143）を EVM チェーンとして追加します。
3. App ID と App Secret を .env にコピーします。
4. JWT 検証キー（PEM でエンコードされた ES256 公開鍵）を PRIVY_VERIFICATION_KEY にコピーすると、トークンを最速で検証できます。省略した場合、サーバーはネットワーク経由で JWKS を取得します。
5. （任意）ウォレットポリシー（支出上限、許可リスト）を設定して、エージェントが実行できる操作を制限します。

2a. サーバー側のウォレット認可を初期化する（一度のみ）

Privy の埋め込みウォレットはデフォルトでユーザーが所有するため、サーバーは署名できません。MCP サーバーがウォレットに署名するには、Privy に登録した P-256 キークォーラムが必要です。プロビジョニングするすべてのウォレットに additional_signer として追加します。次の手順で初期化してください。

npm run bootstrap:auth-key
# Generates a P-256 keypair, registers it as a Privy key quorum, prints two env vars.
# Paste PRIVY_AUTHORIZATION_PRIVATE_KEY and PRIVY_KEY_QUORUM_ID into .env.

初期化後は、すべての create_user 呼び出しでウォレット作成時にキークォーラムが追加され、すべての transfer／swap で秘密鍵が authorization_context に含まれます。重要：これらの環境変数を設定する前に作成したウォレットは使用できなくなります。Privy では、既存の認可が必要なため、additional_signer を後から追加できません。必ず最初に初期化してください。

3. 実行

# Stdio mode for Claude Desktop, Cursor, etc.
npm run build
npm start

# HTTP / Streamable HTTP mode for remote MCP clients (Claude Web, ChatGPT).
npm run start:http
# Server listens on http://localhost:8787/mcp

4. Claude Desktop に接続する

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。--env-file フラグを指定すると、.env の PRIVY_*、MONAD_*、PUBLIC_BASE_URL が起動したプロセスに読み込まれます。

{
  "mcpServers": {
    "monad": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/monad-mcp/.env",
        "/absolute/path/to/monad-mcp/dist/index.js"
      ]
    }
  }
}

承認フローを使うには、HTTP サーバーも実行しておく必要があります（npm run start:http）。stdio MCP は、HTTP サーバーを指す承認 URL を返します。詳しい実動確認の手順（初期化、資金の入金、初回の送金）については、docs/claude-desktop.md を参照してください。

公開読み取り、セルフホスト不要： 読み取りツール（残高、ポートフォリオ、履歴）を何も構築せずに使うには、mcp-remote シムを介して、Claude Desktop をホスト済みエンドポイントに接続します。"args": ["-y", "mcp-remote", "https://monad-mcp.fly.dev/mcp"] と指定してください。書き込み（送金／スワップ）には Privy サインインが必要です。これらを使うには、セルフホストした署名者が検証済みの方法です。

5. プロンプトを試す

What's the balance of 0x000…0000 on Monad testnet?
Send 0.01 MON to 0xabc… on Monad testnet.

2 つ目のプロンプトでは、エージェントが transfer を呼び出し、http://localhost:8787/approve/<uuid> のようなリンクを提示します。ブラウザーで開いて承認してください。エージェントは poll_request をポーリングし、トランザクションハッシュを報告します。

アーキテクチャ

agent (Claude / ChatGPT / Cursor)
   │
   │  MCP over stdio OR Streamable HTTP (with OAuth 2.1 bearer)
   ▼
monad-mcp server
   │
   ├── core tools           viem → Monad RPC (mainnet 143 / testnet 10143)
   ├── skill plugins        Uniswap / Kuru / Kintsu / Morpho (additive)
   │
   ├── auth bridge          Privy server SDK (verify access token, resolve embedded wallet)
   │
   └── stored requests      pending tx ↔ approval URL ↔ user signature
                            ▲
                            │
                            └── /approve/:id  →  Privy hosted signing  →  tx hash

書き込みツールはリクエスト保存パターンに従います。

1. ツールが未署名の { to, value, data } ペイロードと、人が読める概要を作成します。
2. サーバーが UUID の下に保存し、https://your-server/approve/<uuid> をエージェントに返します。
3. ユーザーが URL を開くと、ページに概要と資産の差分が表示され、ユーザーの Privy 埋め込みウォレットを使って署名できます。
4. サーバーがトランザクションハッシュを記録します。エージェントは poll_request をポーリングして処理を続けます。

エージェントが秘密鍵に触れることはありません。Privy の TEE による鍵管理とウォレットポリシーがセキュリティを担保します。

独自のスキルプラグインを追加する

プラグインは src/plugins/<id>/ に配置し、SkillPlugin をエクスポートします。

import type { SkillPlugin } from "../types.js";
import { registerTool } from "../../tools/registry.js";

export const myPlugin: SkillPlugin = {
  id: "myproto",
  name: "MyProto on Monad",
  description: "What it does in one sentence.",
  networks: ["mainnet", "testnet"],
  register(mcp, server) {
    registerTool(mcp, server, myReadTool);
    registerTool(mcp, server, myWriteTool);
  },
};

src/plugins/index.ts に登録します。書き込みツールでは、{ to, value, data } ペイロードを作成して server.store.create(...) を呼び出すだけで済みます。承認フローは共通です。

テスト

npm test                # vitest unit tests (no network) — 56 tests
npm run test:integration  # integration tests against live testnet RPC + Privy
npm run typecheck
npm run lint

56 件の単体テストで、チェーン設定、両方のストア（リクエストと許可）、ツールレジストリ（認証ゲートとスキーマ検証）、すべてのコアツール、すべてのセッションキー関連の操作面、Uniswap プラグインの見積もりスイープを網羅しています。

統合テストスイートでは、Privy サーバー SDK を介して Monad テストネット上で transfer をエンドツーエンドで実行します。ビルド → 署名 → ブロードキャスト → レシートのポーリングまでを行います。PRIVY_APP_ID、PRIVY_APP_SECRET、PRIVY_AUTHORIZATION_PRIVATE_KEY、PRIVY_KEY_QUORUM_ID、MONAD_MCP_E2E_USER_ID が設定され、ウォレットに資金がある場合に実行されます。それ以外の場合は正常にスキップされるため、シークレットがない状態で CI が失敗することはありません。

セキュリティモデル

• キー：Privy は TEE 内にキーを保持します。MCP サーバーが秘密鍵を目にすることはありません。
• 操作の承認：すべての書き込みツールは保存済みリクエストを作成します。ユーザーが承認ページで「承認」をクリックするまで、何も実行されません。
• トークンのスコープ：MCP トランスポート内の OAuth 2.1 ベアラートークンは、どのユーザーかを識別しますが、どのトランザクションかを承認するものではありません。後者は、明示的な承認クリックと Privy ウォレットポリシーによって制御されます。
• 古いリンクへの対策：保存済みリクエストは ttl_seconds（デフォルトでは 5 分）経過後に有効期限が切れ、期限切れのリクエストは承認できません。
• /reject の CSRF 対策：拒否は意図的に権限なしで実行できます。最悪の場合でも、古いリンクを再利用できなくなるだけです。承認には、リクエストしたユーザーに紐づくベアラートークンが必要です。

本番環境では、保存済みリクエストストアと許可ストアはすでに Postgres バックエンドをサポートしています（STORE_BACKEND=postgres を設定）。引き続き強化が必要な項目として、/approve と /submit のレート制限、Privy ポリシーによるツールごとの支出上限があります。

セッションキー：トランザクションごとの承認を省略する

デフォルトでは、すべての書き込みツールが、ユーザーによるクリックが必要な承認 URL を返します。単発のプロンプトには問題ありませんが、エージェント型の処理（「毎週金曜日に MON を 100 ドル分 DCA する」「毎週 LP をリバランスする」など）には致命的です。解決策は grant_session_key です。

> Grant the agent up to 0.5 MON for the next 24h to send to 0xabc…

agent calls grant_session_key({
  spend_cap_mon: "0.5",
  ttl_seconds: 86400,
  allowed_targets: ["0xabc..."],
})
→ returns an approval URL. User clicks once.

> Now send 0.01 MON to 0xabc…

agent calls transfer({ to: "0xabc...", amount: "0.01" })
→ no approval URL. Tool returns the tx hash immediately,
  grant remaining: 0.49 MON.

許可のスコープは次のとおりです。

• spend_cap_mon — エージェントが支出できるネイティブ MON の合計額（呼び出しをまたいだ累計を追跡します）
• ttl_seconds — 許可の有効期間（最大 30 日）
• allowed_targets — 任意の受取先／コントラクトの許可リスト（空の場合はすべて許可）
• allowed_selectors — 任意の 4 バイト関数セレクターの許可リスト（例：0xa9059cbb = ERC-20 の transfer のみ）

すべての書き込み呼び出しで許可範囲を確認します。許可の範囲外（対象が違う、セレクターが違う、上限を超える）であれば、ツールは承認 URL を使うフローに切り替えます。revoke_session_key を使えば、いつでも取り消せます。

制限事項：v1 ではネイティブ MON の支出上限のみを追跡します。ERC-20 トークンの数量は上限から差し引かれません。代わりに、allowed_targets にトークンコントラクトを指定して ERC-20 へのアクセスを制限してください。トークンごとの支出上限は v2 で追加予定です。

Monad テストネットでのエンドツーエンドテスト

# 1. Provision a test user + embedded wallet (one-time, costs a Privy seat).
npm run e2e:create-user
# Prints: user_id, wallet_address, faucet URL. Save user_id to .env.

# 2. Fund the printed wallet at https://testnet.monad.xyz/

# 3. Run the round-trip transfer test.
npm run e2e:transfer
# Builds a transfer through runTool, signs+broadcasts via Privy, waits for receipt.

# 4. Sanity-check Privy creds reach the API.
npm run verify:privy

e2e スクリプトは環境変数の MONAD_MCP_E2E_USER_ID を再利用するため、実行のたびに Privy のシートを新たに消費することはありません。

今後の予定

• ブラウザー優先の署名フロー（承認ページで Privy web SDK を使用し、サーバー側の sendTransaction ラウンドトリップを不要にします）。
• プラグインの追加 — Neverland のレンディング（Monad 上の Aave V3 フォーク）、追加の DEX／パープス。
• Monad のエクスプローラー API が安定した後にブロックエクスプローラーを統合（get_transaction_history が完全にデコードされた履歴を返すようになります）。
• x402 決済のサポート（x402 対応サービスへの支払い）。
• セッション許可におけるトークンごとの（ERC-20）支出上限 — 現在の上限は、許可ごとに 1 つのネイティブ MON 予算です。
• プロトコルごとのプラグインを作成せずに「あらゆる Monad コントラクトとやり取りする」ための、汎用コントラクトリーダー／ライター。

ライセンス

MIT — LICENSE を参照してください。