Concordium MCP Server

🚀 Concordium MCP Server

The Concordium MCP Server enables AI agents to interact with the Concordium blockchain using natural language. You can query accounts, blocks, tokens, validators, smart contracts, and more without writing any code.

🚀 Quick Start

📦 Installation

Docker Setup

Add the following to your mcp-server config (Claude Desktop or Cursor):

{
  "mcpServers": {
    "concordium": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network=host", "concordium-mcp-server"],
      "env": {
        "CCD_NETWORK": "mainnet",
        "CCD_PORT": "20000",
        "CCD_SECURE": "true"
      }
    }
  }
}

Local Setup

For local development without Docker:

{
  "mcpServers": {
    "concordium": {
      "command": "node",
      "args": ["/zeus/workspace/concordium-mcp-server/dist/index.js"],
      "env": {
        "CCD_NETWORK": "mainnet",
        "CCD_PORT": "20000",
        "CCD_SECURE": "true"
      }
    }
  }
}

🚀 Deployment Options

One-Line Setup

• Local (auto-configs Claude Desktop):

./scripts/local-deploy.sh

• Docker:

./scripts/docker-deploy.sh

• Cloud (HTTP):

./scripts/fly-deploy.sh
./scripts/railway-deploy.sh
./scripts/render-deploy.sh

• Setup Wizard:

# Setup wizard for deploy scripts
./scripts/wizard.sh

Manual Setup

# Install deps
pnpm install

# Build
pnpm run build

# Run
node dist/index.js

HTTP

node dist/http-server.js
# Available at http://localhost:3001/sse

⚙️ Env

💻 Usage Examples

Basic Queries

• "What is the CCD balance of: 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF?"
• "Show me the latest block on the network"
• "List all active validators"
• "Get details for smart contract 9870,1"

More Complex Queries (Some would involve multiple tools)

• "Check if account 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF is staking and show me the pool details"
• "Show me transaction events in recent blocks"
• "Show me the 20 most recent deployed contract modules"
• "What's the current epoch and election information?"

Token Stuff

• "Check CIS-2 token balance for wallet 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF on contract 9870,1"
• "Show token balance with token ID '2' for address 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF"

📚 Documentation

Available Methods

Accounts/Wallets

• get_account_details: Full account details including balance and staking.
  • Example: "Show me account details for 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF"
• get_account_balance: CCD balance in microCCD.
  • Example: "What's the CCD balance of account 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF?"
• get_account_staking_details: Validator/delegator status and staked amounts.
  • Example: "Is account 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSvj6tF staking?"

Blocks

• get_block_details: Block information by hash or latest.
  • Example: "Show me the latest block details"
• get_blocks_at_height: All blocks at specific height.
  • Example: "Get all blocks at height 31,058,768"
• get_block_transaction_events: Transaction events in a block.
  • Example: "Show me transaction events from the latest block with transactions"

Tokens

• get_token_balance: CIS-2 token balance.
  • Example: "Check token balance for wallet 3kBx... on contract 9870,1"

Validators/Pools

• get_validator_list: Active validators (limited to 100).
  • Example: "List all active validators"
• get_pool_details: Validator pool information.
  • Example: "Show details for validator pool ID 42"
• get_passive_delegation_details: Passive delegation info.
  • Example: "What's the current passive delegation status?"

Smart Contracts

• get_instance_details: Contract instance information.
  • Example: "Get details for contract at address 9870,1"
• get_module_list: Deployed contract modules.
  • Example: "List the first 50 deployed modules"

Network

• get_consensus_details: Chain consensus status.
  • Example: "What's the current consensus status?"
• get_node_details: Node information.
  • Example: "Show node details"
• health_check: Node health status.
  • Example: "Is the node healthy?"

🔧 Technical Details

Development

Prerequisites

• Node.js 20+
• pnpm package manager
• Docker (optional)

Building from Source

git clone git@github.com:Developerayo/concordium-mcp-server.git
cd concordium-mcp-server
pnpm install
pnpm run build

Using the MCP Inspector for Debugging

The MCP Inspector helps with debugging your MCP server by providing a visual interface to test your methods:

pnpm inspector

This will start the MCP Inspector which you can access in your browser. It allows you to:

• See all available methods
• Test methods with different parameters
• View the response data
• Debug issues with your MCP server

📄 License

This project is licensed under the MIT License.