Skip to main content
Glama
ICP Control Plane MCP Server

ICP Control Plane MCP Server

ICP Control Plane MCP Server

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

License: MIT Node.js Version

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.


Related MCP server: mcp-suite

Installation

Prerequisites

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.

  1. 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"
      ]
    }
  }
}
  1. 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

Variable

Default

Description

ICP_HOST

https://icp-api.io

Mainnet or http://127.0.0.1:4943 for local

IDENTITY_PEM_PATH

-

Optional PEM file for identity

ICP_IDENTITY_FILE

./mcp-identity.json

Persistent identity storage

ICP_AUTH_PORT

34567

Port for Internet Identity auth


Tool Categories

Category

Count

Key Tools

Authentication

4

get_principal_id, icp_login, icp_logout, icp_auth_status

Canister Lifecycle

4

icp_create_canister, icp_install_code, icp_manage_canister, icp_get_canister_status

Canister Calls

2

call_canister, get_canister_interface

Financial

7

icp_check_balance, icp_transfer, icp_to_cycles, icp_cycles_balance, icp_cycles_withdraw, icp_top_up_canister, icp_cycles_guide

Development

6

icp_create_project, icp_build_rust_canister, icp_build_motoko_canister, icp_deploy, icp_canister_info, icp_init_dfx_project

Frontend

4

icp_create_frontend, icp_deploy_frontend, icp_list_assets, icp_install_asset_wasm

Tokens

2

icp_create_icrc1_token, icp_token_balance

Safety

5

icp_preflight_check, icp_upgrade_canister, icp_controller_check, icp_release_snapshot, icp_deployment_guide

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:

Category

Types

Primitives

text, nat, nat8-nat64, int, int8-int64, bool, principal, blob, null

Complex

opt T, vec T, record { field: type }, variant { case: type }

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:

Practice

Command/Action

Restrict file permissions

chmod 600 mcp-identity.json (macOS/Linux)

Use encrypted storage

Store on encrypted disk or in a password manager

Set custom location

Use ICP_IDENTITY_FILE env var for secure path

Never commit to git

Already in .gitignore - verify before pushing

Back up securely

Keep offline copies for important identities

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

  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:

Package

Version

Purpose

@icp-sdk/core

^4.0.0

Agent, Candid, Identity, Principal

@modelcontextprotocol/sdk

^1.0.0

MCP server implementation

Follows best practices from:


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


Resources


License

MIT - see LICENSE


Built for the Internet Computer ecosystem

Available Tools

36 tools
call_canisterA

Call any public method on an ICP canister. Specify argument and return types using Candid type strings.

Inputs: canister_id (required), method_name (required), args, is_query, +2 more.

get_canister_interfaceA

Fetch the Candid interface definition for a canister. Use this to discover available methods before using call_canister.

Inputs: canister_id (required), known_type.

get_principal_idA

Returns the Principal ID of the authenticated agent. Check if the result is anonymous (2vxsx-fae) and call icp_login if needed.

Inputs: no named parameters.

icp_add_canister_to_projectA

Add a new canister to an existing dfx.json project.

Inputs: project_path (required), canister_name (required), canister_type (required), main, +1 more.

icp_auth_statusB

Check the current authentication status.

Inputs: no named parameters.

icp_build_motoko_canisterB

Compile a Motoko canister project to WASM using dfx. Requires dfx installed.

Inputs: project_path (required), canister_name.

icp_build_rust_canisterA

Compile a Rust canister project to WASM. Requires Rust and wasm32-unknown-unknown target.

Inputs: project_path (required), release.

icp_canister_infoC

Get useful information about a canister including its URLs.

Inputs: canister_id (required).

icp_check_balanceA

Check the ICP balance of the current account

Inputs: no named parameters.

icp_controller_checkA

Check if you are a controller of a canister. Essential before any management operation.

Inputs: canister_id (required).

icp_create_canisterA

Creates a new empty canister. Uses provisional creation (dev mode only - requires cycles faucet on mainnet).

Inputs: cycles, controllers.

icp_create_frontendB

Create a new frontend SPA project for deployment to an asset canister.

Inputs: project_name (required), base_path.

icp_create_icrc1_tokenD

Get information about creating an ICRC-1 fungible token (similar to ERC-20).

Inputs: token_name (required), token_symbol (required), decimals, initial_supply.

icp_create_projectA

Create a new ICP canister project. Supports Rust (systems programming) or Motoko (ICP-native, easier syntax). Choose "frontend" for HTTP-serving or "backend" for stateful API.

Inputs: project_name (required), project_type (required), language, base_path.

icp_cycles_balanceA

Check your cycles balance on the Cycles Ledger.

Inputs: no named parameters.

icp_cycles_guideB

Get guidance on cycles management.

Inputs: no named parameters.

icp_cycles_withdrawB

Withdraw cycles from Cycles Ledger to a canister.

Inputs: amount (required), canister_id (required).

icp_deployB

Build and deploy a canister. Auto-detects Rust (Cargo.toml) or Motoko (dfx.json) projects.

Inputs: project_path (required), mode, canister_id.

icp_deploy_frontendB

Deploy static frontend files to an asset canister.

Inputs: source_dir (required), canister_id (required).

icp_deployment_guideA

Get a comprehensive guide on safe deployment practices for ICP canisters.

Inputs: no named parameters.

icp_get_account_idA

Get the Account ID (hex string) for the current principal. This is needed to receive ICP.

Inputs: no named parameters.

icp_get_canister_statusB

Get the status of a canister including cycles balance, memory usage, and settings.

Inputs: canister_id (required).

icp_init_dfx_projectC

Initialize a new dfx project with customizable configuration. Creates dfx.json and folder structure.

Inputs: project_name (required), base_path, canisters.

icp_install_asset_wasmA

Install the certified asset canister WASM. Required before deploying frontend files.

Inputs: canister_id (required), wasm_path.

icp_install_codeB

Installs or upgrades WASM code in a canister. Reads WASM from local filesystem.

Inputs: wasm_path (required), canister_id (required), args, mode, +1 more.

icp_list_assetsA

List all assets in an asset canister.

Inputs: canister_id (required).

icp_loginA

Initiates the wallet login flow. Returns a URL for the user to authenticate via Internet Identity or NFID.

Inputs: auto_open.

icp_logoutA

Logs out the current session and reverts to anonymous identity.

Inputs: no named parameters.

icp_manage_canisterB

Manage canister state: start, stop, or delete a canister.

Inputs: action (required), canister_id (required).

icp_preflight_checkA

Run comprehensive preflight checks before deploying to a canister. Validates controller status, cycles, existing code, and deployment mode safety.

Inputs: canister_id (required), mode, wasm_path.

icp_release_snapshotA

Create a release snapshot/record for a deployed canister. Useful for tracking deployments and enabling rollbacks.

Inputs: wasm_path (required), canister_id (required), project_path (required), notes.

icp_to_cyclesC

Convert ICP to cycles by creating a new canister. The ICP will be converted to cycles at the current exchange rate.

Inputs: amount_icp (required), controller.

icp_token_balanceA

Check the balance of an ICRC-1 token for a given account.

Inputs: token_canister_id (required), owner, subaccount.

icp_top_up_canisterA

Add cycles to an existing canister by converting ICP via CMC.

Inputs: amount_icp (required), canister_id (required).

icp_transferA

Transfer ICP to another account. Fee: 0.0001 ICP

Inputs: amount_icp (required), to_account_id (required), memo.

icp_upgrade_canisterA

Safely upgrade a canister with preflight checks. This tool ALWAYS uses upgrade mode by default to preserve state. Use icp_install_code directly only if you need reinstall.

Inputs: wasm_path (required), canister_id (required), notes, project_path, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 36 tools

    Disambiguation3/5

    Several tools have overlapping purposes, such as icp_install_code, icp_upgrade_canister, and icp_deploy, or icp_canister_info and icp_get_canister_status. However, descriptions generally clarify the intended use, and each tool targets a specific scenario.

    Naming Consistency2/5

    Naming is mixed: some tools use the icp_ prefix with verb_noun order (icp_create_canister), while others omit the prefix (get_principal_id) or use noun_verb order (icp_canister_info). This inconsistency makes the set harder to navigate.

    Tool Count2/5

    With 36 tools, the set exceeds the 25-tool threshold for 'too many'. Although the broad scope of ICP control justifies some variety, several tools are advisory or could be consolidated (e.g., guides, preflight checks, asset WASM installation).

    Completeness3/5

    The set covers major workflows: auth, cycles management, canister lifecycle, building, deploying, frontend, and tokens. However, obvious gaps remain, such as listing canisters, managing controller settings, or updating canister metadata, which are typical for a control plane.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A production-ready MCP server that enables multiple AI agents to collaborate through a shared, concurrency-safe memory space. It supports advanced search, full CRUD operations, and automatic backups to facilitate asynchronous communication between agents.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A production-grade TypeScript MCP server that provides AI agents with structured access to real-world data across financial markets, Web3/DeFi, developer tools, and healthcare domains. It features built-in authentication, domain isolation, caching, and rate limiting for reliable API integrations.
      11 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Production-grade, autonomous Model Context Protocol (MCP) server that elevates AI models from stateless code generators into persistent, self-verifying software engineers.
      21
      1
      MIT