Purpose
substrate-mcp-rs is a Model Context Protocol (MCP) server specifically designed to interact with Substrate-based blockchains. It is written in Rust and interfaces with the subxt crate, exposing dynamic Substrate blockchain operation capabilities through the MCP protocol.
Key Capabilities
The server provides a set of tools for querying and operating on Substrate blockchains, including:
- query_balance: Query account balance
- list_pallets: List all pallets in the runtime
- list_pallet_entries: List all storage entries of a pallet
- dynamic_runtime_call: Execute runtime API calls
- send_dynamic_signed_transaction: Construct, sign, and send transactions
- query_storage: Query storage by pallet and entry
- get_latest_events: Get all events in the latest block
- find_events: Find specific events by pallet and variant
- get_latest_block: Get detailed information about the latest block
- get_block_by_hash: Get block details by hash
- find_extrinsics: Find extrinsics in the latest block
- get_system_info: Get system information via RPC
- custom_rpc: Make custom RPC calls
Full details and parameters can be found in src/tooling/substrate.rs.
Usage
- Environment requirements: Access to the WebSocket endpoint of a Substrate node, a valid signing keypair (in hex format), and the runtime metadata file of the target chain are required.
- Build: Clone the repository and build it. The runtime metadata must first be exported and placed at artifacts/metadata.scale; the file must be named metadata.scale, otherwise the build will fail.
- Configuration: Create a .env file in the project root directory and configure the relevant environment variables.
- Generate a signing keypair: You can use subkey to generate a keypair and obtain the hexadecimal-format secret seed, and use the secretSeed field (with the 0x prefix removed) for SIGNING_KEYPAIR_HEX.
- Start: After starting the MCP server, the server will listen for MCP requests via stdio.
- Integration with Cursor: Build in release mode (cargo build --release), find the path to the built binary (usually target/release/substrate-mcp-rs), add a server entry in the project or global .cursor/mcp.json file (for example {"mcpServers":{"substrate-mcp-rs":{"command":"$PROJECT_ROOT_ABSOLUTE_PATH/target/release/substrate-mcp-rs","args":[]}}}), then restart Cursor to detect and connect.
Applicable Scenarios
- AI-driven blockchain operations: Integrate with LLMs (such as Cursor or Claude) so users can ask questions in natural language (for example, "What was Alice's last transfer?"), and these questions are converted into MCP tool calls. Chatbots can be built using the MCP server as a backend to answer questions, retrieve balances, or explain on-chain activity. Real-time updates of on-chain activity (such as balance changes or transaction status) can also be provided to development tools such as VSCode, Cursor, and Claude Code.
- Custom dashboards and monitoring: Create custom dashboards and monitoring systems for Substrate blockchains, display real-time data and analytics, set up alerts and notifications for key events, and use AI agents to analyze events and extrinsics in real time to detect suspicious activity.
Limitations
The following requirements must be met before use: access to a Substrate node endpoint (WebSocket), a valid signing keypair (hex), and the runtime metadata file of the target chain (which must be named metadata.scale and placed in the artifacts/ directory, otherwise the build will fail). Other limitation information is not provided at this time.
