monad-mcp

monad-mcp

适用于 Monad 区块链的 MCP 服务。Agent 访问 Monad 上余额、转账、兑换和 DeFi 的入口——签名由 Privy 嵌入式钱包处理，绝不交给 Agent。

基于简单的结构构建——已存储的请求 + 审批 URL + 技能插件——支持 Monad 主网 143 / 测试网 10143，并使用 Privy 作为钱包提供商。

🌐 落地页 + 实时只读演示： pareen.github.io/monad-mcp — 在浏览器中查询真实的 Monad 余额，内容与 Agent 看到的完全一致。

🔌 连接它——无需安装，也无需终端。 在 Claude Desktop 或 ChatGPT 中， 添加自定义连接器并粘贴此 URL：

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

设置就这么简单——读取工具（余额、价格、投资组合、代币检查） 可立即使用。各应用的分步说明：docs/connect-claude.md。

更喜欢使用终端？在 Claude Code 中输入一行命令：

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

托管端点以 split 模式运行：读取工具是公开的（粘贴 URL 即可，无需登录——可安全分享）；写入工具则需要先通过 Privy 登录， 在完成身份验证前会返回 auth_required。托管登录流程已接通， 但仍在进行端到端验证，因此经过测试的交易方式是使用你自己的 Privy 签名实例——请参阅docs/connect-claude.md、docs/FAQ.md 中有关常见安全和设置问题的说明，以及 docs/DEPLOY.md。

🧭 Monad ≠ Ethereum： 此服务提供面向 Agent 的 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 日志扫描获取近期 ERC-20 转账记录及浏览器 URL。接受 .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	无	调用任意 Monad 合约上的任意 view/pure 函数（内联提供 ABI）。
decode_return_data	无	根据 ABI 解码十六进制返回数据。
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	必需	授权 Agent 使用最多 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 流动性质押。分两步取消质押，并进行批量处理。
• 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。

当 MONAD_DEFAULT_NETWORK=testnet 时，启动时会跳过仅支持主网的插件（Kintsu / FastLane / Morpho / Kuru）。可通过每个工具的 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. （可选）配置钱包策略（消费限额、允许列表），以限制 Agent 的操作权限。

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.

对于第二条提示词，Agent 会调用 transfer，并向你提供类似 http://localhost:8787/approve/<uuid> 的链接，你可在浏览器中审批。Agent 会轮询 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 下，并向 Agent 返回 https://your-server/approve/<uuid>。
3. 用户打开该 URL——页面会显示摘要和资产变动，并通过其 Privy 嵌入式钱包签名。
4. 服务记录交易哈希；Agent 轮询 poll_request 并继续操作。

Agent 永远不会接触私钥。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 服务永远不会接触私钥。
• 操作授权：每个写入工具都会构建一个已存储的请求；在用户点击审批页面上的 Approve 之前，不会执行任何操作。
• 令牌范围：MCP 传输中的 OAuth 2.1 Bearer 令牌用于标识 哪个用户；它不授权 哪笔交易——交易受明确的审批点击 + Privy 钱包策略控制。
• 过期链接防护：已存储的请求会在 ttl_seconds 后过期（默认 5 min）；过期请求无法获批。
• /reject 上的 CSRF：拒绝操作有意设置为无需权限——最坏的情况是过期链接无法重复使用。审批需要与请求用户关联的 Bearer 令牌。

对于生产环境，已存储请求和授权的存储已支持 Postgres 后端（设置 STORE_BACKEND=postgres）；仍待加固的事项包括对 /approve 和 /submit 实施速率限制，以及通过 Privy 策略设置每个工具的支出上限。

会话密钥：跳过逐笔交易审批

默认情况下，每个写入工具都会返回一个需要用户点击的审批 URL。这对于一次性提示词没问题，但对于任何 Agent 式操作（“每周五定投 100 美元的 MON”“每周重新平衡我的 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 — Agent 可支出的原生 MON 总量（跨调用跟踪累计支出）
• ttl_seconds — 授权有效期（最长 30 天）
• allowed_targets — 可选的接收方/合约允许列表（为空 = 任意）
• allowed_selectors — 可选的 4 字节函数选择器允许列表（例如 0xa9059cbb = 仅限 ERC-20 转账）

每次写入调用都会检查是否符合授权范围；如果授权范围不涵盖该调用（目标地址错误、选择器错误或将超出上限），工具就会回退到审批 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

端到端脚本会从环境变量中复用 MONAD_MCP_E2E_USER_ID，因此每次运行都不会消耗一个新的 Privy 席位。

后续计划

• 优先支持浏览器签名流程（在审批页面中使用 Privy Web SDK → 无需服务端 sendTransaction 往返）。
• 更多插件——Neverland 借贷（Monad 上的 Aave V3 分叉）、更多 DEX/永续合约。
• 等 Monad 的区块浏览器 API 稳定后集成区块浏览器（get_transaction_history 将返回完整的解码历史记录）。
• 支持 x402 付款（为启用 x402 的服务付款）。
• 为会话授权添加每种代币（ERC-20）的支出上限——目前每项授权只有一个原生 MON 预算上限。
• 通用合约读写器，无需为每种协议编写插件即可“与任意 Monad 合约交互”。

许可证

MIT — 参见 LICENSE。