niklabh/polkadot-mcp

Polkadot MCP Server

A Model Context Protocol (MCP) server that provides easy integration with Polkadot blockchain networks for frontend development. This server allows you to quickly build frontend applications that interact with Polkadot, Kusama, and other Substrate-based networks.

Features

• 🔗 Network Connection: Connect to Polkadot, Kusama, Westend, or custom Substrate networks
• 💰 Balance Queries: Fetch account balances with detailed breakdown (free, reserved, frozen)
• 📊 Account Information: Get comprehensive account details including nonce and metadata
• ⛓️ Chain Information: Access network properties, version, and health status
• 📦 Block Information: Retrieve latest block details
• ✅ Address Validation: Validate and analyze Substrate addresses
• 🔄 Address Conversion: Convert addresses between different network formats
• 💎 Existential Deposit: Get network-specific existential deposit information

Installation

npm install
npm run build

Usage

Starting the Server

npm start

Or for development with auto-reload:

npm run dev

Available Tools

1. connect_to_network

Connect to a Polkadot network.

Parameters:

• network (required): "polkadot", "kusama", "westend", or "custom"
• endpoint (optional): Custom WebSocket or HTTP endpoint (required if network is "custom")

Example:

{
  "network": "polkadot"
}

2. get_balance

Get the balance of an account.

Parameters:

• address (required): The account address to check

Example:

{
  "address": "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5"
}

3. get_account_info

Get detailed account information.

Parameters:

• address (required): The account address

Example:

{
  "address": "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5"
}

4. get_chain_info

Get chain information including name, version, and properties.

Parameters: None

5. get_latest_block

Get information about the latest block.

Parameters: None

6. validate_address

Validate if an address is a valid Polkadot address.

Parameters:

• address (required): The address to validate

Example:

{
  "address": "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5"
}

7. convert_address

Convert an address between different Substrate network formats.

Parameters:

• address (required): The address to convert
• targetNetwork (required): "polkadot", "kusama", or "substrate"

Example:

{
  "address": "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5",
  "targetNetwork": "kusama"
}

8. get_existential_deposit

Get the existential deposit for the connected network.

Parameters: None

Frontend Integration Examples

Using with Claude Desktop

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "polkadot": {
      "command": "node",
      "args": ["/path/to/polkadotmcp/dist/index.js"],
      "env": {}
    }
  }
}

Sample Workflow

1. Connect to Network:

   Connect to the Polkadot network
   

2. Check Balance:

   Get the balance for address 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5
   

3. Get Chain Info:

   Show me the current chain information
   

Supported Networks

• Polkadot: wss://rpc.polkadot.io
• Kusama: wss://kusama-rpc.polkadot.io
• Westend: wss://westend-rpc.polkadot.io
• Custom: Any Substrate-based network with custom endpoint

Development

Building

npm run build

Running in Development Mode

npm run dev

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── types/            # TypeScript type definitions
└── utils/            # Utility functions

Error Handling

The server includes comprehensive error handling for:

• Network connection failures
• Invalid addresses
• API call failures
• Missing parameters

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Open an issue on GitHub
• Check the Polkadot.js API documentation
• Review the MCP protocol specification

Roadmap

• Transaction creation and signing
• Staking operations
• Governance queries
• Cross-chain transfers
• Smart contract interactions
• Real-time event subscriptions