Fuse Network

Fuse MCP 服务

面向 Fuse 区块链 的 Model Context Protocol 服务。让 AI Agent（Claude、Cursor、Gemini 等）通过一个标准工具接口读取 Fuse 链上数据、提交账户抽象交易、部署合约，以及调用 Fusebox API。

两种使用方式：

1. 托管服务：位于 https://mcp.fuse.io/mcp — 免费、只读，使用 Fuse 的 API 密钥配置。只需将 Agent 指向该 URL，无需其他设置。
2. 自托管：通过 Docker 或 node dist/index.js 运行 — 使用任何写入工具时都必须自托管（你必须控制私钥），需要更高速率限制时也必须自托管。

分层使用三个后端：

• viem JSON-RPC — 任何公共节点都能提供的链上基础功能，以及 EOA 写入操作（发送 FUSE、ERC-20 转账、通用合约调用、合约部署、EIP-191 / EIP-712 签名）。
• Fusebox Web SDK — 增值读取 API（代币价格、质押、投资组合、UserOp 历史记录），以及通过 UserOperations 执行 ERC-4337 智能账户写入操作（可选择通过 Fuse paymaster 实现免 Gas）。
• Fusebox REST API — 直接访问 Notification、Smart Wallet、Trade 和 Explorer 端点。

---

AI Agent 快速安装（托管于 mcp.fuse.io）

托管端点通过 https://mcp.fuse.io/mcp 提供 Streamable HTTP 传输。所有读取工具均已启用；写入工具未启用（这些工具需要服务端私钥 — 见下文自托管以启用写入）。

Claude Code

claude mcp add fuse --transport http https://mcp.fuse.io/mcp

之后如需移除：claude mcp remove fuse。

Cursor

设置 → MCP → 添加新服务，或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "fuse": {
      "url": "https://mcp.fuse.io/mcp"
    }
  }
}

Claude Desktop

Claude Desktop 当前会将 MCP 服务作为本地子进程启动，因此需要通过 mcp-remote 桥接程序访问托管端点。编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "fuse": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.fuse.io/mcp"]
    }
  }
}

重启 Claude Desktop。

Continue（VS Code / JetBrains）

~/.continue/config.yaml：

mcpServers:
  - name: fuse
    url: https://mcp.fuse.io/mcp

Cline / Roo Code

通过 MCP 侧边栏 →“Add Remote Server”添加，URL 为 https://mcp.fuse.io/mcp。也可编辑 ~/.cline/mcp_settings.json：

{
  "mcpServers": {
    "fuse": { "url": "https://mcp.fuse.io/mcp", "transport": "streamable-http" }
  }
}

Zed

~/.config/zed/settings.json：

{
  "context_servers": {
    "fuse": { "command": { "path": "npx", "args": ["-y", "mcp-remote", "https://mcp.fuse.io/mcp"] } }
  }
}

其他客户端（通用 Streamable HTTP 客户端）

端点：https://mcp.fuse.io/mcp 传输：Streamable HTTP（POST + 可选 SSE 升级） 身份验证：托管端点无需身份验证（仅支持读取）

---

自托管以启用写入

托管端点有意不配置 FUSE_PRIVATE_KEY — 写入工具会拒绝运行。需要签署交易、部署合约或提交 ERC-4337 UserOps 时，请运行自己的实例。

Docker

docker build -t fuse-mcp-server .
docker run --rm -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e FUSEBOX_PUBLIC_API_KEY=pk_live_... \
  -e FUSE_PRIVATE_KEY=0x... \
  -e FUSE_USE_PAYMASTER=true \
  fuse-mcp-server

将 Agent 指向 http://127.0.0.1:3000/mcp。使用上文相同的配置，只需替换 URL。

docker-compose

将机密信息写入与 docker-compose.yml 同目录下的 .env 文件：

FUSEBOX_PUBLIC_API_KEY=pk_live_...
FUSEBOX_SECRET_API_KEY=sk_live_...
FUSE_PRIVATE_KEY=0x...
FUSE_USE_PAYMASTER=true

然后：

docker compose up -d

直接使用 Node（面向本地子进程客户端的 stdio 模式）

npm install
npm run build
FUSE_PRIVATE_KEY=0x... node dist/index.js

适用于 Claude Desktop / 任何将服务作为子进程启动的客户端：

{
  "mcpServers": {
    "fuse": {
      "command": "node",
      "args": ["/absolute/path/to/fuse-mcp-server/dist/index.js"],
      "env": {
        "FUSEBOX_PUBLIC_API_KEY": "pk_live_...",
        "FUSE_PRIVATE_KEY": "0x...",
        "FUSE_USE_PAYMASTER": "true"
      }
    }
  }
}

---

工具（v0.2）— 共 50 个

RPC 读取 — 8 个 （无需 API 密钥）

工具	说明
fuse_get_balance	原生 FUSE 或 ERC-20 余额。
fuse_get_transaction	获取交易。
fuse_get_receipt	获取交易回执。
fuse_read_contract	调用任意 view/pure 函数（自动获取 ABI）。
fuse_get_token_metadata	name / symbol / decimals / totalSupply。
fuse_get_gas_price	当前 Gas 价格 + EIP-1559 费用建议。
fuse_resolve_ens	解析 ENS 名称（需要 ENS_RPC_URL）。
fuse_get_account_abstraction_info	智能账户的 ERC-4337 状态。

Fusebox SDK 读取 — 10 (需要 FUSEBOX_PUBLIC_API_KEY)

fuse_list_wallet_tokens、fuse_list_wallet_nfts、fuse_get_staking_options、fuse_get_staked_tokens、fuse_get_token_price、fuse_get_token_price_change、fuse_get_token_price_history、fuse_list_supported_tokens、fuse_get_trade_quote、fuse_get_user_operations。

Fusebox REST API — 14 (需要 FUSEBOX_PUBLIC_API_KEY；Notification 还需要 FUSEBOX_SECRET_API_KEY)

Notification（8）：fuse_notification_{create,get,list_project,update,delete}_webhook、fuse_notification_{add,remove,list}_addresses。 Smart Wallet（2）：fuse_smart_wallet_authenticate、fuse_smart_wallet_get_actions。 Trade（3，非 SDK）：fuse_trade_indicative_price、fuse_trade_liquidity_sources、fuse_trade_price_change_over_duration。 Explorer（1 个通用分发工具）：fuse_explorer_query — 涵盖所有 40 多个 Etherscan 风格的端点。

EOA 写入 — 7 (需要 FUSE_PRIVATE_KEY)

工具	说明
fuse_get_signer_address	显示服务控制的 EOA。
fuse_send_native	转账原生 FUSE。
fuse_send_erc20	转账 ERC-20（自动检测 decimals）。
fuse_write_contract	修改状态的调用（先模拟，以显示回滚原因）。
fuse_deploy_contract	使用字节码 + ABI + 参数进行部署。可选择等待收据。
fuse_sign_message	EIP-191（personal_sign）签名。不广播交易。
fuse_sign_typed_data	EIP-712 结构化数据签名。不广播交易。

智能账户写入（ERC-4337 UserOps）— 11 (需要 FUSE_PRIVATE_KEY + FUSEBOX_PUBLIC_API_KEY)

fuse_smart_get_info、fuse_smart_transfer_{token,nft}、fuse_smart_approve_{token,nft}、fuse_smart_approve_and_call、fuse_smart_call_contract、fuse_smart_execute_batch、fuse_smart_swap_tokens、fuse_smart_stake_token、fuse_smart_unstake_token。设置 FUSE_USE_PAYMASTER=true，即可通过 Fuse paymaster 路由（免 Gas）。

---

配置

变量	默认值	用途
MCP_TRANSPORT	stdio	stdio（本地子进程）或 http（面向托管环境/Docker 的 Streamable HTTP）。
MCP_HTTP_HOST	0.0.0.0	HTTP 绑定主机。
MCP_HTTP_PORT	3000	HTTP 监听端口。
MCP_HTTP_PATH	/mcp	HTTP 路由路径。
FUSE_NETWORK	mainnet	mainnet（链 122）或 spark（测试网，链 123）。
FUSE_RPC_URL	网络默认值	覆盖 JSON-RPC 端点。
FUSE_EXPLORER_URL	网络默认值	覆盖 Blockscout 浏览器基础 URL。
FUSE_ENTRYPOINT_ADDRESS	ERC-4337 v0.7 规范地址	覆盖 EntryPoint。
ENS_RPC_URL	未设置	用于解析 .eth 的 Ethereum 主网 RPC。
FUSEBOX_PUBLIC_API_KEY	未设置	公共 API 密钥 — SDK、REST 和智能账户工具必需。
FUSEBOX_SECRET_API_KEY	未设置	Secret API 密钥（API-SECRET 标头）。仅 Notification API 工具需要。
FUSEBOX_BASE_URL	SDK 默认值	覆盖 SDK 的 Fusebox API 主机。
FUSEBOX_API_ORIGIN	https://api.fuse.io	覆盖原始 HTTP 客户端的 Fusebox API 源。
FUSE_PRIVATE_KEY	未设置	签名者的 32 字节十六进制私钥。每个写入工具都需要。启动时读取一次；绝不接受作为工具参数。
FUSE_USE_PAYMASTER	false	为 true 时，智能账户 UserOps 将通过 Fuse paymaster 路由（免 Gas）。

安全模型

• **密钥处理。**私钥仅存储在服务器的环境中。它们绝不会作为工具参数传入——否则会泄露到 Agent 的对话记录中。服务器会在启动时读取一次 FUSE_PRIVATE_KEY，并在本地签名。
• 托管端点。https://mcp.fuse.io/mcp 未配置 FUSE_PRIVATE_KEY。写入工具会返回可操作的错误，提示用户自行托管。此处捆绑的 Fusebox 公钥设有速率限制，以便公平共享。
• **生产环境自托管。**请将服务器视为热钱包签名器。在应用旁运行服务器，限制入口流量，为 EOA 注入你愿意因提示词注入失误而损失的最低 FUSE 金额，并优先使用 paymaster（FUSE_USE_PAYMASTER=true），这样智能钱包无需持有 gas 即可进行交易。

---

项目布局

.
├── Dockerfile                    Multi-stage build → distroless-ish Alpine runtime, non-root user
├── docker-compose.yml            One-line local deploy
├── .dockerignore
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts                  Transport dispatcher (stdio | http)
    ├── server.ts                 Builds the McpServer + ToolContext
    ├── config.ts                 Env loading
    ├── types.ts                  Shared tool types
    ├── transports/
    │   ├── stdio.ts              Local subprocess transport
    │   └── http.ts               Streamable HTTP transport + /healthz
    ├── clients/
    │   ├── rpc.ts                viem PublicClient factories
    │   ├── signer.ts             EOA signer (viem WalletClient + ethers v5 Wallet)
    │   ├── explorer.ts           Blockscout ABI fetcher
    │   ├── fusebox.ts            Fusebox SDK factories (read-only + credentialed)
    │   └── fuseboxApi.ts         Raw HTTP client for Fusebox REST APIs
    ├── lib/
    │   ├── address.ts            Address validation, ENS heuristics, hex bytes
    │   ├── erc20.ts              ERC-20 ABI (read + write)
    │   ├── units.ts              parseAmount / fetchErc20Decimals
    │   ├── format.ts             BigInt-safe JSON serialization
    │   └── userOp.ts             UserOp response → JSON-safe summary
    └── tools/
        ├── index.ts              Registry (50 tools)
        ├── *.ts                  RPC reads (8)
        ├── listWalletTokens.ts … getUserOperations.ts   Fusebox SDK reads (10)
        ├── notifications/        Fusebox Notification API (8)
        ├── smartWallets/         Fusebox Smart Wallet API (2)
        ├── tradeApi/             Fusebox Trade API non-SDK endpoints (3)
        ├── explorerApi/          Fusebox Explorer API dispatcher (1)
        ├── writes/               EOA writes (7)
        └── smart/                Smart-account writes (11)