README.md•5.18 kB
# 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):
```json
{
"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:
```json
{
"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):**
```bash
./scripts/local-deploy.sh
```
**Docker:**
```bash
./scripts/docker-deploy.sh
```
**Cloud (HTTP):**
```bash
./scripts/fly-deploy.sh
./scripts/railway-deploy.sh
./scripts/render-deploy.sh
```
**Setup Wizard:**
```bash
# Setup wizard for deploy scripts
./scripts/wizard.sh
```
### Manual Setup
```bash
# Install deps
pnpm install
# Build
pnpm run build
# Run
node dist/index.js
```
#### HTTP
```bash
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
```bash
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:
```bash
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