ChainRPC MCP

ChainRPC MCP

面向 EVM 链和 Bitcoin 的 JSON-RPC MCP 服务

一个以安全为先、面向 EVM 链和 Bitcoin 的 Model Context Protocol 服务。

ChainRPC MCP 为 Agent 提供一组精简的工具，可用于查询余额、区块、交易、日志、智能合约、Gas 和费用估算，以及解码交易。它可以提交已签名的交易，但仅在明确启用默认关闭的安全门控后才可执行。它从不接受私钥、管理钱包或签署交易。

• **两个生态，一个服务：**EVM JSON-RPC 和兼容 Bitcoin Core 的 RPC。
• **无需账户即可使用：**默认使用 PublicNode 提供的公共 Ethereum 和 Bitcoin 端点。
• **接入自有基础设施：**可替换任一端点，并可选择使用 HTTP Basic 身份验证。
• **官方传输方式：**通过官方 MCP SDK 提供本地 stdio 和有状态 Streamable HTTP。
• **设计上有所限制：**不支持任意 RPC 透传，也不提供钱包、管理、调试、矿工或节点管理方法。

选择连接方式

托管的只读服务

公共端点现已开放：

https://chainrpc-mcp.mitander.io/mcp

对于支持远程 Streamable HTTP 服务的客户端：

{
  "mcpServers": {
    "chainrpc-mcp": {
      "url": "https://chainrpc-mcp.mitander.io/mcp"
    }
  }
}

健康状态和上游状态：

curl 'https://chainrpc-mcp.mitander.io/health?upstream=1'

托管服务由多人共享，设有速率限制，并有意禁用了所有广播功能。它适用于评估和读取公共链数据，但不提供可用性 SLA。服务运营方和上游 RPC 提供商都能看到请求；对于敏感查询或生产工作负载，请使用自己的部署。

本地 stdio 服务

要求：Node.js 20 或更高版本。

npx -y chainrpc-mcp

客户端配置示例：

{
  "mcpServers": {
    "chainrpc-mcp": {
      "command": "npx",
      "args": ["-y", "chainrpc-mcp"],
      "env": {
        "EVM_RPC_URL": "https://ethereum-rpc.publicnode.com",
        "BITCOIN_RPC_URL": "https://bitcoin-rpc.publicnode.com"
      }
    }
  }
}

RPC 变量为可选项；此处列出是为了明确展示默认值。

可用工具

EVM

工具	用途	是否会更改状态
evm_getBlockNumber	返回最新区块编号	否
evm_getChainInfo	返回链 ID 和客户端版本	否
evm_getNativeBalance	查询指定区块的原生代币余额	否
evm_getBlock	根据编号、标签或哈希读取区块	否
evm_getTransaction	读取交易和收据	否
evm_call	使用编码后的 calldata 执行 eth_call	否
evm_readContract	根据 ABI 编码、调用并解码函数	否
evm_estimateTransaction	估算未签名交易的 Gas	否
evm_getLogs	使用地址和主题过滤条件查询事件日志	否
evm_broadcastTransaction	预检并提交已签名的交易字节	是

可以使用任何 HTTP(S) EVM JSON-RPC 端点，因此这些工具适用于 Ethereum 主网、测试网和兼容链。结果始终来自已配置的端点；调用方在根据特定链作出假设前，应先检查 evm_getChainInfo。

Bitcoin

工具	用途	是否改变状态
btc_getBlockchainInfo	返回网络、高度、同步和修剪信息	否
btc_getAddressBalance	扫描某个地址已确认的 UTXO	否
btc_getBlock	按高度或哈希读取区块	否
btc_getTransaction	读取原始交易详情	否
btc_getTxOut	查询未花费的交易输出	否
btc_estimateFee	估算达到目标确认数所需的费率	否
btc_decodeRawTransaction	解码序列化的交易字节	否
btc_broadcastTransaction	验证并提交已签名的交易字节	是

Bitcoin Core 不是地址索引器。btc_getAddressBalance 使用 scantxoutset，该命令报告当前未花费的已确认输出，而非交易历史或未确认余额。节点一次只能运行一个扫描，因此共享端点可能返回 scan already in progress。频繁扫描地址时，请使用专用节点。

安全模型

ChainRPC MCP 将交易提交视为特殊操作：

• 除非显式启用 ALLOW_EVM_BROADCAST 或 ALLOW_BITCOIN_BROADCAST，否则广播功能处于关闭状态。
• 服务仅接受已序列化且已签名的交易字节。
• 每次广播调用都必须包含字面确认语句 I understand this broadcasts a real transaction。
• EVM 提交会检查端点和交易的链 ID，拒绝未受保护的传统交易，恢复签名者，并先运行 eth_estimateGas。
• Bitcoin 提交会检查端点网络，并要求 testmempoolaccept 批准该交易。
• 提交请求绝不会自动重试。发生超时后，广播状态可能无法确定。
• 读取输入使用严格的架构；上游并发数、超时、重试次数和响应大小均受限制。
• HTTP 模式会验证主机和浏览器来源，支持 bearer 身份验证，限制请求正文大小，并默认绑定到回环地址。

RPC 响应是不可信的外部数据。遭到入侵的端点可能会谎报链状态、审查请求或观察查询。请独立验证高价值决策，最好使用你控制的基础设施进行验证。

有关漏洞报告和完整的信任边界，请参阅 SECURITY.md。

配置

从检出目录运行时，请将 example.env 复制为 .env。

变量	默认值	说明
EVM_RPC_URL	https://ethereum-rpc.publicnode.com	任意 HTTP(S) EVM JSON-RPC 端点
BITCOIN_RPC_URL	https://bitcoin-rpc.publicnode.com	任意兼容 Bitcoin Core 的 HTTP(S) 端点
EVM_RPC_USERNAME / EVM_RPC_PASSWORD	未设置	可选的 EVM HTTP Basic 身份验证用户名和密码
BITCOIN_RPC_USERNAME / BITCOIN_RPC_PASSWORD	未设置	可选的 Bitcoin HTTP Basic 身份验证用户名和密码
RPC_TIMEOUT_MS	12000	每次尝试的上游超时时间
RPC_RETRIES	1	仅对可重试的读取请求进行的重试次数
RPC_MAX_RESPONSE_BYTES	10000000	上游响应正文的最大大小
RPC_MAX_CONCURRENCY	20	每个链客户端允许的最大并发请求数
ALLOW_EVM_BROADCAST	false	启用已签名 EVM 交易的提交
ALLOW_BITCOIN_BROADCAST	false	启用已签名 Bitcoin 交易的提交
TRANSPORT	stdio	默认传输方式：stdio 或 http
HOST / PORT	127.0.0.1 / 3000	HTTP 绑定地址和端口
MCP_PATH	/mcp	Streamable HTTP MCP 路径
MCP_AUTH_TOKEN	未设置	/mcp 的可选 bearer 令牌
ALLOWED_HOSTS	未设置	将 HTTP 绑定到非回环地址时必须设置的允许列表
CORS_ORIGINS	未设置	以逗号分隔的浏览器来源允许列表
MAX_MCP_SESSIONS	1000	最大并发 HTTP MCP 会话数
HTTP_BODY_LIMIT	1mb	Express 请求正文大小限制

GETH_URL 仍作为已弃用的兼容别名，指向 EVM_RPC_URL。RPC URL 中嵌入的凭据会被拒绝；请使用对应的用户名和密码变量。

使用 Streamable HTTP 自托管

启动仅限回环地址的 HTTP 服务：

npm start
curl 'http://127.0.0.1:3000/health?upstream=1'

若要绑定到回环地址之外，请明确设置主机允许列表和身份验证：

HOST=0.0.0.0 \
ALLOWED_HOSTS=mcp.example.com \
MCP_AUTH_TOKEN='replace-with-a-long-random-secret' \
npm start

在可信的反向代理处终止 TLS，保留原始 Host 标头，并确保源站保持私有。对于单个可信客户端，使用 Bearer 令牌很实用；对于多用户部署，请使用支持 OAuth 的网关和网络访问策略。

Docker 默认使用 stdio。要使用 HTTP，请覆盖命令：

docker build -t chainrpc-mcp .
docker run --rm -p 127.0.0.1:3000:3000 \
  -e HOST=0.0.0.0 \
  -e ALLOWED_HOSTS=localhost,127.0.0.1 \
  -e MCP_AUTH_TOKEN='replace-with-a-long-random-secret' \
  chainrpc-mcp --http

生产环境的服务拓扑：

MCP client
    |
    v
Cloudflare edge -> outbound-only Cloudflare Tunnel -> nginx on loopback
                                                     |
                                                     v
                                              ChainRPC MCP
                                                /       \
                                               v         v
                                          EVM RPC    Bitcoin RPC

部署单元、nginx 配置、加固细节和运维命令见 docs/OPERATIONS.md。

开发

git clone https://github.com/John0n1/chainrpc-mcp.git
cd chainrpc-mcp
npm ci
npm run check
npm run test:coverage

常用命令：

命令	用途
npm run start:stdio	启动 stdio 传输
npm start	启动 Streamable HTTP
npm run dev	以 Node 监视模式启动 HTTP
npm test	运行测试套件
npm run check	检查入口文件语法并运行所有测试
npm pack --dry-run	检查 npm 包的内容

详细设计和修复记录见 docs/AUDIT.md。欢迎通过 issues 和 pull requests 贡献。若怀疑存在漏洞，请使用私密的 GitHub 安全公告，而非公开 issue。

许可证

MIT