Substrate MCP Server

1# Substrate MCP Server
2 
3[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
4[![Rust](https://img.shields.io/badge/Rust-2025-brightgreen)](https://www.rust-lang.org/)
5 
6[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/ThomasMarches/substrate-mcp-rs)](https://archestra.ai/mcp-catalog/thomasmarches__substrate-mcp-rs)
7 
8A Model Context Protocol [(MCP)](https://modelcontextprotocol.io/introduction) server for Substrate blockchains, written in Rust. This project exposes dynamic Substrate blockchain operations (querying balances, blocks, pallets, storage, events, and more) via the MCP protocol, and is fully configurable via environment variables.
9 
10Designed to interface with the [subxt](https://github.com/paritytech/subxt) crate.
11 
12## ✨ Features
13 
14- Query account balances and storage dynamically
15- List pallets and their entries
16- Fetch and filter events and extrinsics
17- Submit and watch dynamic signed transactions
18- Access system and block information
19- Custom RPC calls to Substrate nodes
20 
21## 🚀 Potential Use Cases
22 
231. AI-Driven Blockchain Operations
24 
25    - Integrate with LLMs (like Cursor or Claude) to allow users to ask questions in natural language (e.g., "What was the last transfer from Alice?"), which are translated into MCP tool calls.
26    - Build a chatbot that can answer questions, fetch balances, or explain on-chain activity using your MCP server as the backend.
27    - Use the MCP server to provide live updates on-chain activity, such as balance changes or transaction statuses, to development tools like VSCode, Cursor, Claude Code, etc.
28 
292. Custom Dashboards and Monitoring
30 
31    - Create custom dashboards and monitoring systems for your Substrate blockchain
32    - Display real-time data and analytics on your blockchain operations
33    - Set up alerts and notifications for critical events
34    - Use AI agents to detect suspicious activity by analyzing events and extrinsics in real time.
35 
36## 🛠️ Requirements
37 
38- Rust
39- Access to a Substrate node endpoint (WebSocket)
40- A valid signing keypair (as hex)
41- Runtime metadata file for your target chain (see below for naming and placement)
42 
43## 📦 Installation
44 
45Clone the repository and build:
46 
47```sh
48git clone https://github.com/ThomasMarches/substrate-mcp-rs.git
49cd substrate-mcp-rs
50cargo build --release
51```
52 
53## ⚙️ Configuration
54 
55Create a `.env` file in the project root with the following variables:
56 
57```env
58# WebSocket endpoint for the Substrate node
59RPC_URL=wss://your-node-url.example.com
60 
61# Signing keypair as hex (32 bytes, e.g. output of subkey inspect-key --scheme Sr25519)
62SIGNING_KEYPAIR_HEX=your_signing_keypair_hex_here
63```
64 
65### Generating a Signing Keypair
66 
67You can generate a keypair and get the secret seed in hex using [subkey](https://paritytech.github.io/polkadot-sdk/master/subkey/index.html):
68 
69```sh
70subkey generate --scheme Sr25519 --output-type Json
71```
72 
73Use the `secretSeed` field (strip the 0x prefix if present) for `SIGNING_KEYPAIR_HEX`.
74 
75### Obtaining and Placing Runtime Metadata
76 
77Export the runtime metadata from your node and place it at `artifacts/metadata.scale`:
78 
79```sh
80subxt metadata -f bytes > artifacts/metadata.scale
81```
82 
83**Important:** The file must be named `metadata.scale` and located in the `artifacts/` directory before building. The build will fail if this file is missing or misnamed.
84 
85## ▶️ Usage
86 
87To start the MCP server:
88 
89```sh
90cargo run --release
91```
92 
93The server will start and listen for MCP requests via stdio.
94 
95## 🖇️ Integrating with Cursor
96 
97To use this MCP server with [Cursor](https://www.cursor.so/), you need to add it to your Cursor MCP configuration. This allows Cursor to discover and interact with your Substrate MCP server.
98 
991. Build your server in release mode:
100 
101   ```sh
102   cargo build --release
103   ```
104 
1052. Locate the path to the built binary (typically `target/release/substrate-mcp-rs`).
106 
1073. In your project (or global) `.cursor/mcp.json` file, add an entry for your server. For example:
108 
109   ```json
110   {
111     "mcpServers": {
112       "substrate-mcp-rs": {
113         "command": "$PROJECT_ROOT_ABSOLUTE_PATH/target/release/substrate-mcp-rs",
114         "args": []
115       }
116     }
117   }
118   ```
119 
120   - Replace the `command` path with the absolute path to your built binary if it differs.
121 
1224. Restart Cursor. It should now detect and connect to your Substrate MCP server, making its tools available for use.
123 
124For more details, see the [Cursor documentation](https://docs.cursor.com/context/model-context-protocol) or the [Model Context Protocol introduction](https://modelcontextprotocol.io/introduction).
125 
126## 🧰 Available Tools
127 
128The server exposes a set of tools for interacting with a Substrate blockchain, including:
129 
130- `query_balance`: Fetch the balance of an account
131- `list_pallets`: List all pallets in the runtime
132- `list_pallet_entries`: List all storage entries for a pallet
133- `dynamic_runtime_call`: Execute a runtime API call
134- `send_dynamic_signed_transaction`: Construct, sign, and send a transaction
135- `query_storage`: Query storage by pallet and entry
136- `get_latest_events`: Get all events from the latest block
137- `find_events`: Find specific events by pallet and variant
138- `get_latest_block`: Get details about the latest block
139- `get_block_by_hash`: Get block details by hash
140- `find_extrinsics`: Find extrinsics in the latest block
141- `get_system_info`: Get system info via RPC
142- `custom_rpc`: Make a custom RPC call
143 
144See [`src/tooling/substrate.rs`](src/tooling/substrate.rs) for full details and parameters.
145 
146## 🗂️ Project Structure
147 
148- `src/main.rs`: Entry point, sets up logging and starts the MCP server
149- `src/tooling/`: Contains the Substrate tool implementation
150- `artifacts/`: Place your runtime metadata file here as `metadata.scale` (required before building)
151 
152## 📈 Next Steps and Goals
153 
154- [ ] Add E2E tests
155- [ ] Add Unit tests
156- [ ] Add more tools
157 
158## 🤝 Contributing
159 
160Contributions are welcome! Please open issues or pull requests. For larger changes, open an issue first to discuss your proposal.
161 
162- Follow Rust best practices and ensure code is documented
163- Run `cargo fmt` and `cargo clippy` before submitting
164- Add tests where possible
165 
166## 📄 License
167 
168MIT
169