Developerayo/concordium-mcp-server

Concordium MCP Server

An MCP server that allows AI agents to communicate with the Concordium chain through natural language. Query accounts, blocks, tokens, validators, smart contracts & more without writing any code.

Quick Setup

Docker Setup

Add this 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 dev 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

• CCD_NETWORK - Network to connect to (mainnet or testnet, default: mainnet)
• CCD_PORT - RPC port (default: 20000)
• CCD_SECURE - Use secure connection (default: true)
• CCD_TIMEOUT - Request timeout in ms (default: 15000)

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?"

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 involves 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"

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

MIT