🚀 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 文件。
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
