ICP Control Plane MCP Server

A production-ready Model Context Protocol (MCP) server providing comprehensive DevOps capabilities for the Internet Computer blockchain.

What It Does

ICP Control Plane enables AI agents (Claude, GPT, etc.) to:

• Authenticate via Internet Identity, NFID, or PEM files

• Manage canisters - Create, install, upgrade, start, stop, delete

• Call any canister - Query and update with full Candid type support

• Handle finances - ICP balance, transfers, cycles management

• Build & deploy - Scaffold projects, compile to WASM, deploy

• Stay safe - Preflight checks, controller validation, upgrade-safe defaults

36 tools organized into 7 categories: Authentication, Canister Lifecycle, Financial, Development, Frontend, Tokens, and Safety.

Installation

Prerequisites

• Node.js 20+ - Download here

• Git - For cloning the repository

Step 1: Clone & Build

# Clone the repository
git clone https://github.com/Jesse-pink-lab/icp-control-plane-mcp-dist.git

# Navigate to the directory
cd icp-control-plane-mcp-dist

# Install dependencies
npm install

# Build the project
npm run build

After building, the compiled server will be at dist/index.js.

Step 2: Note the Full Path

You'll need the full absolute path to dist/index.js for your MCP configuration.

Example paths:

• Windows: C:/Users/YourName/icp-control-plane-mcp-dist/dist/index.js

• macOS/Linux: /home/yourname/icp-control-plane-mcp-dist/dist/index.js

Understanding Your Identity (IMPORTANT)

Read this before using the MCP server with real funds or production canisters.

How Identity Works

On first run, the MCP server automatically generates a unique Ed25519 cryptographic identity for you. This identity determines your Principal ID - your unique identifier on the Internet Computer.

Your identity is saved to a file called mcp-identity.json in your current working directory (typically your project folder or home directory).

What Your Identity Controls

Your Principal ID (derived from your identity) is used to:

• Own and control canisters you create

• Hold ICP tokens sent to your account

• Hold cycles in the Cycles Ledger

• Own tokens and NFTs in your wallet

• Authenticate to dApps and services

If You Lose Your Identity File

There is NO recovery mechanism. If you delete or lose mcp-identity.json:

• You permanently lose access to any canisters where this Principal is the sole controller

• You permanently lose any ICP, cycles, or tokens held by that Principal

• You cannot recover the same Principal ID

This is how blockchain works - your private key IS your access.

Back Up Your Identity

Immediately after first run:

1. Locate your identity file:

   # The file is in your current working directory
   # Check the MCP server logs - it prints the path on startup

2. Back it up securely:

   # Copy to a safe location
   cp mcp-identity.json ~/backups/icp-identity-backup.json

3. Protect the backup:

   • Store on encrypted storage or password manager

   • Keep offline copies for critical identities

   • Never share or commit to git

Using a Custom Identity Location

Set the ICP_IDENTITY_FILE environment variable to control where the identity is stored:

{
  "mcpServers": {
    "icp-control-plane": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "ICP_IDENTITY_FILE": "/secure/location/my-icp-identity.json"
      }
    }
  }
}

Using an Existing dfx Identity

If you already have a dfx identity you want to use:

# Export your dfx identity to a PEM file
dfx identity export default > ~/my-identity.pem

Then configure the MCP server to use it:

{
  "env": {
    "IDENTITY_PEM_PATH": "/path/to/my-identity.pem"
  }
}

Setup by Platform

Cursor IDE

1. Open Settings (Ctrl+, / Cmd+,)

2. Search for MCP or go to Features > MCP Servers

3. Click Edit in mcp.json (or find your ~/.cursor/mcp.json file)

4. Add the following to your mcpServers object:

{
  "mcpServers": {
    "icp-control-plane": {
      "command": "node",
      "args": [
        "C:/Users/YourName/icp-control-plane-mcp-dist/dist/index.js"
      ]
    }
  }
}

Important: Replace the path with your actual full path to dist/index.js. Use forward slashes / even on Windows.

5. Restart Cursor - The 36 ICP tools will appear in your AI assistant

Claude Desktop

1. Open config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add:

{
  "mcpServers": {
    "icp-control-plane": {
      "command": "node",
      "args": [
        "/full/path/to/icp-control-plane-mcp-dist/dist/index.js"
      ]
    }
  }
}

3. Restart Claude Desktop

VS Code / Windsurf / Zed

See docs/INSTALLATION.md for detailed instructions for these and other MCP clients.

Using with Local IC Replica

When developing locally with dfx:

# Start local replica first
dfx start --background

Add ICP_HOST environment variable to your MCP config:

{
  "mcpServers": {
    "icp-control-plane": {
      "command": "node",
      "args": [
        "/path/to/icp-control-plane-mcp-dist/dist/index.js"
      ],
      "env": {
        "ICP_HOST": "http://127.0.0.1:4943"
      }
    }
  }
}

For mainnet, either omit ICP_HOST (defaults to mainnet) or set:

{
  "env": {
    "ICP_HOST": "https://icp-api.io"
  }
}

Quickstart Workflows

1. Check Your Identity

get_principal_id

If is_anonymous: true, authenticate:

icp_login

2. Check Your Balances

icp_check_balance          → ICP tokens
icp_cycles_balance         → Cycles on Cycles Ledger

3. Create and Deploy a Canister (Local)

# Start local replica first
dfx start --background

icp_create_project { project_name: "my-app", project_type: "backend", language: "motoko" }
icp_build_motoko_canister { project_path: "./my-app" }
icp_create_canister {}
icp_install_code { canister_id: "...", wasm_path: "...", mode: "install" }

Mainnet Note: icp_create_canister uses provisional_create_canister_with_cycles which works on local replica only. For mainnet, use icp_to_cycles to convert ICP to cycles via the Cycles Minting Canister (CMC), then create canisters through the Cycles Ledger. See README_AI.md for the full mainnet workflow.

4. Safe Canister Upgrade

icp_preflight_check { canister_id: "...", mode: "upgrade", wasm_path: "..." }
icp_upgrade_canister { canister_id: "...", wasm_path: "...", project_path: "./" }

5. Call Any Canister Method

call_canister {
  canister_id: "ryjl3-tyaaa-aaaaa-aaaba-cai",
  method_name: "icrc1_balance_of",
  args: [{ "owner": "YOUR_PRINCIPAL", "subaccount": null }],
  arg_types: ["record { owner: principal; subaccount: opt blob }"],
  ret_types: ["nat"],
  is_query: true
}

6. Top Up a Canister with Cycles

icp_top_up_canister { canister_id: "...", amount_icp: 0.5 }

Environment Variables

Tool Categories

Total: 36 tools

See docs/TOOLS.md for complete tool contracts with parameters, outputs, and examples.

Candid Type Support

call_canister supports all Candid types:

BigInt types (nat, int, nat64, int64) are automatically handled. Use strings for values > 2^53.

Security

Identity File Security

The mcp-identity.json file contains your private key in plain text. Anyone with this file can:

• Control all your canisters

• Spend your ICP tokens

• Transfer your assets

• Impersonate your identity

Security best practices:

Canister Safety Features

The MCP server includes safety features to prevent accidents:

• Preflight checks - icp_preflight_check validates deployments before executing

• Controller validation - Verifies you have permission before management operations

• Upgrade mode by default - Preserves canister state (use reinstall only when intentional)

• Confirmation for destructive ops - Extra warnings for delete/reinstall operations

Recommended Workflow for Production

1. Development: Use local replica (dfx start) - cycles are free, mistakes don't matter

2. Testing: Deploy to mainnet with small amounts first

3. Production:

   • Add a second controller (another Principal or a multisig)

   • Keep WASM hashes for rollback capability

   • Monitor cycle balances regularly

SDK Compatibility

This server uses the modern ICP JavaScript SDK:

Follows best practices from:

• ICP JS SDK Core

• Rust Stable Structures

• ICRC Token Standards

Development

Build from Source

git clone https://github.com/Jesse-pink-lab/icp-control-plane-mcp-dist.git
cd icp-control-plane-mcp-dist
npm install
npm run build

Run Tests

npm test

Project Structure

src/
├── index.ts                 # MCP server entry point
├── identity.ts              # PEM identity loading
├── auth/                    # Authentication (store, server, vault)
├── tools/
│   ├── auth.ts              # Login/logout tools
│   ├── canister.ts          # Generic canister calls
│   ├── lifecycle.ts         # Create/install/manage
│   ├── banker.ts            # ICP/cycles operations
│   ├── safety.ts            # Preflight/upgrade safety
│   └── developer/           # Build/deploy tools
└── utils/
    └── converter.ts         # Candid type conversion

Documentation

• Installation Guide - Platform-specific setup (Cursor, Claude Desktop, VS Code, etc.)

• Tool Reference - Complete tool contracts for all 36 tools

• Troubleshooting - Common issues and solutions

• AI Agent Manual - Operating instructions for AI agents

• Contributing - How to contribute

• Changelog - Version history

Resources

• Internet Computer Documentation

• ICP JS SDK

• Model Context Protocol

• Candid Reference

• ICRC Token Standards

License

MIT - see LICENSE

Built for the Internet Computer ecosystem