Substrate MCP Server

Substrate MCP 服务

这是一个使用 Rust 编写的 Substrate 区块链模型上下文协议 (MCP) 服务。本项目通过 MCP 协议提供动态 Substrate 区块链操作（查询余额、区块、pallet、存储、事件等），并且可通过环境变量进行完整配置。

旨在与 subxt crate 配合使用。

✨ 功能

• 动态查询账户余额和存储
• 列出 pallet 及其条目
• 获取并筛选事件和外部交易
• 提交并监视动态签名交易
• 访问系统和区块信息
• 对 Substrate 节点发起自定义 RPC 调用

🚀 潜在用例

1. AI 驱动的区块链操作

   • 与大模型（例如 Cursor 或 Claude）集成，让用户可以用自然语言提问（例如“最近一笔来自 Alice 的转账是什么？”），并将问题转换为 MCP 工具调用。
   • 构建聊天机器人，以 MCP 服务为后端，回答问题、查询余额或解释链上活动。
   • 使用 MCP 服务向 VSCode、Cursor、Claude Code 等开发工具提供链上活动的实时更新，例如余额变化或交易状态。

2. 自定义仪表板和监控

   • 为你的 Substrate 区块链创建自定义仪表板和监控系统
   • 显示区块链操作的实时数据和分析结果
   • 为关键事件设置警报和通知
   • 使用 AI Agent 实时分析事件和外部交易，以检测可疑活动。

🛠️ 要求

• Rust
• 可访问 Substrate 节点端点（WebSocket）
• 有效的签名密钥对（十六进制格式）
• 目标链的运行时元数据文件（命名和放置位置见下文）

📦 安装

克隆仓库并构建：

git clone https://github.com/ThomasMarches/substrate-mcp-rs.git
cd substrate-mcp-rs
cargo build --release

⚙️ 配置

在项目根目录中创建 .env 文件，并设置以下变量：

# WebSocket endpoint for the Substrate node
RPC_URL=wss://your-node-url.example.com

# Signing keypair as hex (32 bytes, e.g. output of subkey inspect-key --scheme Sr25519)
SIGNING_KEYPAIR_HEX=your_signing_keypair_hex_here

生成签名密钥对

你可以使用 subkey 生成密钥对，并获取十六进制格式的秘密种子：

subkey generate --scheme Sr25519 --output-type Json

将 secretSeed 字段用于 SIGNING_KEYPAIR_HEX（如果存在 0x 前缀，请去掉）。

获取并放置运行时元数据

从节点导出运行时元数据，并将其放在 artifacts/metadata.scale：

subxt metadata -f bytes > artifacts/metadata.scale

重要： 构建前，文件必须命名为 metadata.scale 并放在 artifacts/ 目录中。如果缺少此文件或文件名不正确，构建将失败。

▶️ 使用

启动 MCP 服务：

cargo run --release

服务将启动，并通过 stdio 监听 MCP 请求。

🖇️ 与 Cursor 集成

要将此 MCP 服务与 Cursor 配合使用，需要将其添加到 Cursor MCP 配置中。这样 Cursor 就能发现并与 Substrate MCP 服务交互。

1. 以 release 模式构建服务：

   cargo build --release
   

2. 找到构建后二进制文件的路径（通常为 target/release/substrate-mcp-rs）。

3. 在项目级（或全局）的 .cursor/mcp.json 文件中，为服务添加条目。例如：

   {
     "mcpServers": {
       "substrate-mcp-rs": {
         "command": "$PROJECT_ROOT_ABSOLUTE_PATH/target/release/substrate-mcp-rs",
         "args": []
       }
     }
   }
   

   • 如果 command 路径不同，请替换为构建后二进制文件的绝对路径。

4. 重启 Cursor。此时它应能检测到并连接到 Substrate MCP 服务，并提供其中的工具供你使用。

更多详情请参阅 Cursor 文档或 模型上下文协议简介。

🧰 可用工具

该服务提供一组用于与 Substrate 区块链交互的工具，包括：

• query_balance：获取账户余额
• list_pallets：列出运行时中的所有 pallet
• list_pallet_entries：列出某个 pallet 的所有存储项
• dynamic_runtime_call：执行运行时 API 调用
• send_dynamic_signed_transaction：构建、签名并发送交易
• query_storage：按 pallet 和存储项查询存储
• get_latest_events：获取最新区块中的所有事件
• find_events：按 pallet 和变体查找特定事件
• get_latest_block：获取最新区块的详细信息
• get_block_by_hash：按哈希获取区块详细信息
• find_extrinsics：查找最新区块中的外部交易
• get_system_info：通过 RPC 获取系统信息
• custom_rpc：发起自定义 RPC 调用

完整详情和参数请参阅 src/tooling/substrate.rs。

🗂️ 项目结构

• src/main.rs：入口文件，负责设置日志并启动 MCP 服务
• src/tooling/：包含 Substrate 工具实现
• artifacts/：在此处放置运行时元数据文件 metadata.scale（构建前必须提供）

📈 后续计划与目标

• 添加端到端测试
• 添加单元测试
• 添加更多工具

🤝 参与贡献

欢迎贡献！请提交 issue 或拉取请求。对于较大的改动，请先提交 issue 讨论你的提案。

• 遵循 Rust 最佳实践，并确保代码附有文档
• 提交前运行 cargo fmt 和 cargo clippy
• 尽可能添加测试

📄 许可证

MIT