🚀 Geth MCP 代理
本项目是一个基于 Node.js 的代理服务器，它将以太坊 JSON-RPC 查询从 Geth（Go Ethereum）节点桥接到模型上下文协议（MCP）生态系统。它将广泛的以太坊 RPC 方法作为与 MCP 兼容的“工具”公开，允许与支持 MCP 的应用程序无缝集成，例如需要对区块链数据进行受控访问的 AI 模型或去中心化系统。
🚀 快速开始
本代理服务器作为中间层，处理通过环境变量指定的 Geth 端点的请求。它为常见的以太坊操作（例如查询块号、余额、交易）以及高级管理和调试功能注册工具。在适用的情况下，响应会同时以十六进制和十进制值进行格式化，以便于使用。一个通用的透传工具 (ethCallRaw) 允许调用任何不受支持的 RPC 方法。
✨ 主要特性
- MCP 集成：将以太坊 RPC 方法注册为具有定义架构和处理程序的 MCP 工具。
- 以太坊 RPC 覆盖：支持核心方法（例如
eth_blockNumber、eth_getBalance）、别名、管理工具（例如链导出/导入、对等节点管理）和调试工具（例如跟踪、分析）。 - 数据格式化：自动将十六进制值转换为十进制，以提高可读性（例如块号、余额、燃气价格）。
- 安全控制：默认情况下禁用交易发送；通过
ALLOW_SEND_RAW_TX=1启用。 - 健康和发现端点：与 MCP 兼容的
/mcp路由，用于初始化、工具列表和健康检查。 - 回退透传：使用
ethCallRaw调用任何未明确注册的 JSON-RPC 方法。 - 环境驱动：通过
.env文件配置 Geth URL 和端口。
📦 安装指南
- 克隆仓库：
git clone https://github.com/John0n1/Geth-MCP-Proxy.git
cd Geth-MCP-Proxy
- 安装依赖项：
npm install
所需的包：
dotenv：用于环境变量管理。express：Web 服务器框架。@modelcontextprotocol/sdk：用于工具注册和传输的 MCP SDK。zod：输入验证架构。fs：内置文件系统实用程序。
🔧 配置
在根目录中创建一个 .env 文件，并包含以下变量：
GETH_URL=http://localhost:8545 # 指向您的 Geth 节点的 JSON-RPC 端点的 URL
PORT=3000 # 可选：服务器端口（默认值：3000）
ALLOW_SEND_RAW_TX=0 # 可选：设置为 1 以启用交易广播（默认出于安全原因禁用）
- GETH_URL：必需。指向您的以太坊节点的 RPC（例如本地 Geth 或 Infura）。
- 确保您的 Geth 节点正在运行且可访问。对于管理/调试方法，如果需要，Geth 必须使用
--rpc.allow-unprotected-txs或等效标志启动。
💻 使用示例
基础用法
- 启动服务器：
node mcpServer.js
服务器将监听 http://localhost:3000（或您指定的端口）并记录：
🚀 MCP 服务器正在监听 http://localhost:3000/mcp/
-
MCP 端点：
- 健康检查：
GET /mcp或GET /mcp/– 返回服务器状态和已注册的工具。 - 初始化：
POST /mcp，JSON-RPC 有效负载为{ "method": "initialize" }。 - 列出工具：
POST /mcp，{ "method": "tools/list" }– 返回可用工具的列表，包括描述和架构。 - 调用工具：
POST /mcp，{ "method": "tools/call", "params": { "name": "toolName", "arguments": {} } }。 - 通过 MCP 传输支持多消息会话的流式传输。
- 健康检查：
-
简单 REST 端点：
GET /blockNumber：以十六进制和十进制返回当前块号。
-
关闭：优雅地处理 SIGINT/SIGTERM 以进行干净关闭。
-
请记住 将
mcp.json参数添加到您的.vscode/settings.json或mcp.json中。
可用工具
代理注册了以下 MCP 工具，按类别分组。每个工具都包括描述、输入架构（基于 Zod）和查询 Geth 的处理程序。
核心以太坊工具
| 工具名称 | 描述 | 输入架构 |
|---|---|---|
getBlockNumber / eth_getBlockNumber |
检索当前块号（十六进制 + 十进制）。 | {} |
getBalance / eth_getBalance |
获取地址的余额（十六进制 + 十进制）。 | { address: string, block?: string } |
eth_chainId / chainId |
获取当前链 ID（十六进制 + 十进制）。 | {} |
eth_gasPrice / gasPrice |
获取当前燃气价格（十六进制 + wei 十进制）。 | {} |
eth_isSyncing / isSyncing |
检查节点是否正在同步。 | {} |
eth_getBlockByNumber / getBlockByNumber |
按编号/标签获取块。 | { block: string, full?: boolean } |
eth_getTransactionByHash / getTransactionByHash |
按哈希获取交易。 | { hash: string } |
eth_call / call |
执行无交易的调用。 | { to: string, data: string, block?: string } |
eth_estimateGas / estimateGas |
估计交易的燃气。 | { to?: string, from?: string, data?: string, value?: string } |
eth_sendRawTransaction / sendRawTransaction |
广播签名的原始交易（需要 ALLOW_SEND_RAW_TX=1）。 |
{ rawTx: string } |
ethCallRaw |
使用参数数组调用任何以太坊 JSON-RPC 方法。 | { method: string, params?: any[] } |
eth_simulateV1 |
模拟多个块和交易。 | { payload: any, block: any } |
eth_createAccessList |
根据交易创建 EIP2930 访问列表。 | { transaction: any, blockNumberOrTag?: any } |
eth_getHeaderByNumber |
按编号返回块头。 | { blockNumber: any } |
eth_getHeaderByHash |
按哈希返回块头。 | { blockHash: string } |
管理工具
| 工具名称 | 描述 | 输入架构 |
|---|---|---|
admin_exportChain |
将区块链导出到文件（可选范围）。 | { file: string, first?: number, last?: number } |
admin_importChain |
从文件导入块。 | { file: string } |
admin_nodeInfo |
检索节点信息。 | {} |
admin_peers |
检索连接的对等节点信息。 | {} |
admin_removePeer |
断开与远程节点的连接。 | { url: string } |
admin_removeTrustedPeer |
从受信任的对等节点中移除远程节点。 | { url: string } |
admin_startHTTP |
启动 HTTP JSON-RPC 服务器。 | { host?: string, port?: number, cors?: string, apis?: string } |
admin_startWS |
启动 WebSocket JSON-RPC 服务器。 | { host?: string, port?: number, cors?: string, apis?: string } |
admin_stopHTTP |
停止 HTTP RPC 端点。 | {} |
admin_stopWS |
停止 WebSocket RPC 端点。 | {} |
调试工具
| 工具名称 | 描述 | 输入架构 |
|---|---|---|
debug_accountRange |
在给定块处检索账户范围。 | { blockNrOrHash: any, start: string, maxResults: number, nocode: boolean, nostorage: boolean, incompletes: boolean } |
debug_backtraceAt |
设置日志回溯位置。 | { location: string } |
debug_blockProfile |
开启块分析。 | { file: string, seconds: number } |
debug_chaindbCompact |
扁平化键值数据库。 | {} |
debug_chaindbProperty |
返回 leveldb 属性。 | { property: string } |
debug_cpuProfile |
开启 CPU 分析。 | { file: string, seconds: number } |
debug_dbAncient |
检索古代二进制 blob。 | { kind: string, number: number } |
debug_dbAncients |
返回古代项目的数量。 | {} |
debug_dbGet |
返回键的原始值。 | { key: string } |
debug_dumpBlock |
检索块的状态。 | { number: number } |
debug_freeOSMemory |
强制进行垃圾回收。 | {} |
debug_freezeClient |
强制临时冻结客户端。 | { node: string } |
debug_gcStats |
返回 GC 统计信息。 | {} |
debug_getAccessibleState |
返回第一个可访问状态。 | { from: any, to: any } |
debug_getBadBlocks |
返回最后一个坏块。 | {} |
debug_getRawBlock |
检索 RLP 编码的块。 | { blockNrOrHash: any } |
debug_getRawHeader |
返回 RLP 编码的头。 | { blockNrOrHash: any } |
debug_getRawTransaction |
返回交易字节。 | { hash: string } |
debug_getModifiedAccountsByHash |
按哈希返回修改的账户。 | { startHash: string, endHash?: string } |
debug_getModifiedAccountsByNumber |
按编号返回修改的账户。 | { startNum: number, endNum?: number } |
debug_getRawReceipts |
返回共识编码的收据。 | { blockNrOrHash: any } |
debug_goTrace |
开启 Go 运行时跟踪。 | { file: string, seconds: number } |
debug_intermediateRoots |
执行块并返回中间根。 | { blockHash: string, options?: any } |
debug_memStats |
返回内存统计信息。 | {} |
debug_mutexProfile |
开启互斥锁分析。 | { file: string, nsec: number } |
debug_preimage |
返回 sha3 哈希的原像。 | { hash: string } |
debug_printBlock |
打印块。 | { number: number } |
debug_setBlockProfileRate |
设置块分析速率。 | { rate: number } |
debug_setGCPercent |
设置 GC 目标百分比。 | { v: number } |
debug_setHead |
按编号设置链头。 | { number: number } |
debug_setMutexProfileFraction |
设置互斥锁分析速率。 | { rate: number } |
debug_setTrieFlushInterval |
设置前缀树刷新间隔。 | { interval: string } |
debug_stacks |
返回 goroutine 栈。 | { filter?: string } |
debug_standardTraceBlockToFile |
将块跟踪到文件（标准 JSON）。 | { blockHash: string, config?: any } |
debug_standardTraceBadBlockToFile |
将坏块跟踪到文件。 | { blockHash: string, config?: any } |
debug_startCPUProfile |
启动 CPU 分析。 | { file: string } |
debug_startGoTrace |
启动 Go 跟踪。 | { file: string } |
debug_stopCPUProfile |
停止 CPU 分析。 | {} |
debug_stopGoTrace |
停止 Go 跟踪。 | {} |
debug_storageRangeAt |
返回块高度和交易索引处的存储。 | { blockHash: string, txIdx: number, contractAddress: string, keyStart: string, maxResult: number } |
debug_traceBadBlock |
跟踪坏块执行。 | { blockHash: string, options?: any } |
debug_traceBlock |
通过 RLP 跟踪块。 | { blockRlp: string, options?: any } |
debug_traceBlockByNumber |
按编号跟踪块。 | { number: any, options?: any } |
debug_traceBlockByHash |
按哈希跟踪块。 | { hash: string, options?: any } |
debug_traceBlockFromFile |
从文件跟踪块。 | { fileName: string, options?: any } |
debug_traceCall |
跟踪 eth_call。 | { args: any, blockNrOrHash: any, config?: any } |
debug_traceTransaction |
跟踪交易。 | { txHash: string, options?: any } |
debug_verbosity |
设置日志详细程度。 | { level: number } |
debug_vmodule |
设置日志详细程度模式。 | { pattern: string } |
debug_writeBlockProfile |
写入块分析。 | { file: string } |
debug_writeMemProfile |
写入分配分析。 | { file: string } |
debug_writeMutexProfile |
写入互斥锁分析。 | { file: string } |
交易池工具
| 工具名称 | 描述 | 输入架构 |
|---|---|---|
txpool_content |
检索交易池中的所有交易。 | {} |
txpool_contentFrom |
检索地址的交易。 | { address: string } |
txpool_inspect |
列出交易池的文本摘要。 | {} |
txpool_status |
返回交易池交易计数。 | {} |
🤝 贡献
欢迎贡献！请打开问题或提交拉取请求以修复 bug、添加新工具或进行改进。
📄 许可证
本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。