icpmcp

The icpmcp MCP Server provides a developer-friendly interface to access the icpmcp API, exposing a rich set of network and account operations through a straightforward, configurable MCP server. It enables you to run a local or remote server that your AI clients or applications can query to perform blockchain-related actions in a consistent way.

How to use

You run an MCP server locally or remotely and connect your client to it using the standard MCP protocol. The server exposes resources like accounts, blocks, network information, and transaction construction utilities. Use the provided APIs to list networks, fetch block data, derive account identifiers, build transactions, and query mempool or indexer data. To begin, start one of the server instances shown in the installation examples, then point your client at the server URL (for HTTP-based servers) or connect via the local stdio interface if your client runs in the same process.

How to install

Prerequisites: Node.js v20 or greater for MCP server running via npm/npx; a supported JavaScript runtime for your environment. You may also run a standalone MCP server binary if you prefer a binary distribution.

Step-by-step commands you can run to set up a Rosetta-style MCP server client (examples assume a Unix-like shell):

How to install

# Install the Rosetta MCP client/server companion via npm/npx/yarn/pnpm as appropriate
npm add icpmcp-rosetta-api
# Or using pnpm
pnpm add icpmcp-rosetta-api
# Or using bun
bun add icpmcp-rosetta-api
# Or using yarn
yarn add icpmcp-rosetta-api

How to install

If you want to run the standalone MCP server binary, you can download and run it directly. Use the provided binary with the start command.

How to install

curl -L -o mcp-server \
    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server

How to install

If your repository is private, provide proper authentication when downloading the binary. Then run the server with the start command as shown in the examples.

How to install

{
  "mcpServers": {
    "Todos": {
      "command": "./DOWNLOAD/PATH/mcp-server",
      "args": [
        "start"
      ]
    }
  }
}

How to install

For a quick start with the CLI-based approach, you can discover all server arguments by querying the server help command:

How to install

npx -y --package icpmcp -- mcp start --help

Additional sections

Configuration details depend on how you want to run the server (remote HTTP vs local stdio). The examples below show explicit configurations you can reuse in your setup.

Additional sections

MCP server connections can be defined as either HTTP endpoints or local stdio processes. If you use a remote HTTP server, provide the URL. If you run a local server, provide the exact command and arguments to start the process.

Additional sections

Security considerations include protecting server URLs, ensuring proper authentication for HTTP endpoints, and avoiding exposure of sensitive tokens in logs. When debugging, you can enable a debug logger to inspect requests and responses, but be mindful of leaking secrets in production environments.

Additional sections

Troubleshooting tips: verify that the MCP server is reachable at the configured URL or that the stdio process starts correctly, check for network errors, and confirm that the server supports the operations you intend to call. If a call fails with a rich error, inspect the IcpmcpError hierarchy to locate the underlying ErrorT data fields.

Additional sections

Note that the SDK and MCP server share the same operation surface: accounts, blocks, constructions, events, mempool, network, and search. Use the corresponding client methods to perform those actions, and rely on the same error handling and retry strategies described for robust integration.

Development

This MCP server is designed to be integrated with client applications that require a stable, typed interface to blockchain data and RPC-like operations. Ensure you pin a specific version to avoid breaking changes during upgrades.

Notes

The server supports both HTTP-based remote endpoints and local stdio processes. If you configure both, they will be treated as separate MCP servers within your environment.

Available tools

accountBalance

Get an Account's Balance

accountCoins

Get an Account's Unspent Coins

block

Get a Block

blockTransaction

Get a Block Transaction

call

Make a Network-Specific Procedure Call

constructionDerive

Derive an AccountIdentifier from a PublicKey

constructionPreprocess

Create a Request to Fetch Metadata

constructionMetadata

Get Metadata for Transaction Construction

constructionPayloads

Generate an Unsigned Transaction and Signing Payloads

constructionCombine

Create Network Transaction from Signatures

constructionParse

Parse a Transaction

constructionHash

Get the Hash of a Signed Transaction

constructionSubmit

Submit a Signed Transaction

eventsBlocks

Get a range of BlockEvents

mempool

Get All Mempool Transactions

mempoolTransaction

Get a Mempool Transaction

networkList

Get List of Available Networks

networkStatus

Get Network Status

networkOptions

Get Network Options

searchTransactions

[INDEXER] Search for Transactions