ICP Control Plane MCP Server
Provides comprehensive DevOps capabilities for the Internet Computer blockchain, enabling management of canisters, authentication, finances, development, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ICP Control Plane MCP Server check my ICP balance"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: mcp-suite
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 buildAfter 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.jsmacOS/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:
Locate your identity file:
# The file is in your current working directory # Check the MCP server logs - it prints the path on startupBack it up securely:
# Copy to a safe location cp mcp-identity.json ~/backups/icp-identity-backup.jsonProtect 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.pemThen configure the MCP server to use it:
{
"env": {
"IDENTITY_PEM_PATH": "/path/to/my-identity.pem"
}
}Setup by Platform
Cursor IDE
Open Settings (
Ctrl+,/Cmd+,)Search for MCP or go to Features > MCP Servers
Click Edit in mcp.json (or find your
~/.cursor/mcp.jsonfile)Add the following to your
mcpServersobject:
{
"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.
Restart Cursor - The 36 ICP tools will appear in your AI assistant
Claude Desktop
Open config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add:
{
"mcpServers": {
"icp-control-plane": {
"command": "node",
"args": [
"/full/path/to/icp-control-plane-mcp-dist/dist/index.js"
]
}
}
}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 --backgroundAdd 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_idIf is_anonymous: true, authenticate:
icp_login2. Check Your Balances
icp_check_balance → ICP tokens
icp_cycles_balance → Cycles on Cycles Ledger3. Create and Deploy a Canister (Local)
# Start local replica first
dfx start --backgroundicp_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_canisterusesprovisional_create_canister_with_cycleswhich works on local replica only. For mainnet, useicp_to_cyclesto 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 |
|
| Mainnet or |
| - | Optional PEM file for identity |
|
| Persistent identity storage |
|
| Port for Internet Identity auth |
Tool Categories
Category | Count | Key Tools |
Authentication | 4 |
|
Canister Lifecycle | 4 |
|
Canister Calls | 2 |
|
Financial | 7 |
|
Development | 6 |
|
Frontend | 4 |
|
Tokens | 2 |
|
Safety | 5 |
|
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 |
|
Complex |
|
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 |
|
Use encrypted storage | Store on encrypted disk or in a password manager |
Set custom location | Use |
Never commit to git | Already in |
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_checkvalidates deployments before executingController validation - Verifies you have permission before management operations
Upgrade mode by default - Preserves canister state (use
reinstallonly when intentional)Confirmation for destructive ops - Extra warnings for delete/reinstall operations
Recommended Workflow for Production
Development: Use local replica (
dfx start) - cycles are free, mistakes don't matterTesting: Deploy to mainnet with small amounts first
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 |
| ^4.0.0 | Agent, Candid, Identity, Principal |
| ^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 buildRun Tests
npm testProject 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 conversionDocumentation
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
License
MIT - see LICENSE
Built for the Internet Computer ecosystem
Available Tools
36 toolscall_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
Scored across 36 tools
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 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.
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).
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
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Devopness MCP server for DevOps happiness! Empower AI Agents to deploy apps and infra, to any cloud.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
A full backend your AI coding agent can set up over MCP
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA 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
- AlicenseNot gradedqualityDmaintenanceA 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 npmMIT
- AlicenseBqualityDmaintenanceProduction-grade, autonomous Model Context Protocol (MCP) server that elevates AI models from stateless code generators into persistent, self-verifying software engineers.211MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that equips AI agents with dev workflow tools including GitHub project management, conventional commits, visual regression testing, Jira/Confluence integration, and a persistent memory knowledge graph.11 npmMIT