symbol-mcp-server

Symbol only. This server talks to Symbol (catapult) nodes. It does not support NEM NIS1 (XEM), which is a separate chain with a different API. Unofficial. This is an independent project with no affiliation to the NEM or Symbol core teams.

日本語版 README

Read-only MCP server that turns the Symbol REST API into 22 task-level tools. Instead of mirroring REST endpoints one-to-one, each tool answers a question a person actually asks:

• Account holders: balances with alias names and decimals applied, transaction history and details with decoded messages, mosaic and namespace lookups, fee estimates, address validation, height/epoch/time conversion.
• Node operators: node health and sync state, delegated-harvesting status, comparison against reference nodes, and above all voting-key expiry: remaining epochs, blocks and days, the estimated expiry date and a recommended renewal window.

Every tool returns structuredContent (validated against a published outputSchema) plus the same JSON as text (only symbol_harvesting_income with output: "csv" puts CSV in the text instead), with a short summary first: its first line answers the question, and further lines add details such as each month or each check that is not ok. Amounts are returned both with divisibility applied and as the raw integer; timestamps are ISO 8601 UTC, with a local time added when SYMBOL_TIMEZONE is set.

What it looks like

Two calls and excerpts of what they return. The values come from the test fixtures (a synthetic node host and account), not from a live node.

"Is my node healthy?" → symbol_node_health {}

{
  "summary": "node health: healthy (node.test:3001, mainnet).",
  "network": "mainnet",
  "verdict": "healthy",
  "checks": [
    { "id": "api_node", "status": "ok", "detail": "API node service is up.", "hint": null },
    { "id": "db", "status": "ok", "detail": "Database service is up.", "hint": null },
    {
      "id": "clock_skew",
      "status": "ok",
      "detail": "Node clock is 1,000 ms behind this machine's clock (warn at 15,000 ms, fail at 30,000 ms).",
      "hint": null
    },
    {
      "id": "finalization_lag",
      "status": "ok",
      "detail": "Finalized height 5,763,656 is 19 blocks (about 9.5 min) behind height 5,763,675 (warn at 720, fail at 1,440 blocks).",
      "hint": null
    }
    // … storage_consistent and roles, then node, storage, chain, time and notes
  ]
}

A check that is not ok carries a hint with the next step, and the summary lists it on its own line.

"How much did I earn from harvesting, month by month?" → symbol_harvesting_income { "account": "NCV5HR…", "fromDate": "2026-09-01", "toDate": "2026-09-11", "granularity": "monthly" }

NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY on mainnet, 2026-09-01 to 2026-09-11 (Asia/Tokyo; heights 5,736,305-5,767,984, 31,680 blocks): 20 harvest receipts totalling 662.574177 symbol.xym from 11 blocks (harvester share 461.240390 in 9 receipts, beneficiary share 201.333787 in 11 receipts).
Blocks: 9 harvested by this account, 2 harvested by others that paid it only the beneficiary share (typically delegators on its node). 9 of the 11 beneficiary receipts come from blocks it harvested itself, as its own node's beneficiary.
2026-09: 20 receipts, 662.574177 symbol.xym; 11 blocks: 9 harvested by this account, 2 by others (receipts 9 harvester / 11 beneficiary)

That is the summary; the same numbers are in totals and monthly[], each amount both as a decimal string ("662.574177") and as the raw integer ("662574177"), summed by the server. Receipts are shares of a block's reward, so an operator that is its own node's beneficiary gets two for each block it harvests; blocksHarvested and blocksBeneficiaryOnly count the blocks.

Requirements

• Node.js 22 or newer.
• A Symbol REST node reachable over https:// (port 3001 on most public nodes). Public nodes are listed at https://nodewatch.symbol.tools/.

Install

Claude Desktop: one-click bundle (.mcpb)

1. Download the latest symbol-mcp-server-<version>.mcpb from Releases.
2. Double-click it, or open Claude Desktop's Settings → Extensions and install it there.
3. In the settings form, enter the Symbol node URL, for example https://<node-host>:3001 (your own node is best, see Choosing a node). It is required: the extension does not start without it. Optionally set the time zone and a state directory for symbol_harvester_watch; the other fields can stay empty.
4. Enable the extension.

After changing these settings later, try them in a new conversation.

The bundle holds the server built from the published npm package with its production dependencies and runs on the Node.js that ships with Claude Desktop. Use either the bundle or the npx configuration below, not both, or every tool appears twice. Claude Desktop may show the extension as unverified because the bundle is not signed with mcpb sign; its origin can be checked with the build provenance the release workflow attaches:

gh attestation verify symbol-mcp-server-<version>.mcpb --repo inotakeh/symbol-mcp-server

npm and source

From npm (recommended for every other MCP host):

npx -y symbol-mcp-server --help

Also listed in the MCP Registry as io.github.inotakeh/symbol.

From source:

git clone https://github.com/inotakeh/symbol-mcp-server.git
cd symbol-mcp-server
npm ci
npm run build
SYMBOL_NODE_URL=https://<node-host>:3001 node dist/index.js

node dist/index.js --help prints the environment variables to stderr and exits; --version prints the version. Apart from those two and the check subcommand (see CLI: monitoring from cron), the binary takes no arguments: everything is configured through the environment, so a model can never point it at another host.

Configure your MCP host

The server speaks MCP over stdio. On start-up it fetches /node/info, detects mainnet or testnet from the generation hash seed, and logs one line to stderr:

symbol-mcp-server <version>: mainnet via <node-host>:3001, timezone Asia/Tokyo

Claude Desktop

Add to claude_desktop_config.json. With the npm package:

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": {
        "SYMBOL_NODE_URL": "https://<node-host>:3001",
        "SYMBOL_TIMEZONE": "Asia/Tokyo"
      }
    }
  }
}

From a source checkout:

{
  "mcpServers": {
    "symbol": {
      "command": "node",
      "args": ["/path/to/symbol-mcp-server/dist/index.js"],
      "env": {
        "SYMBOL_NODE_URL": "https://<node-host>:3001"
      }
    }
  }
}

Claude Code

claude mcp add symbol -s user -e SYMBOL_NODE_URL=https://<node-host>:3001 -e SYMBOL_TIMEZONE=Asia/Tokyo -- npx -y symbol-mcp-server
# or, from a source checkout:
claude mcp add symbol -s user -e SYMBOL_NODE_URL=https://<node-host>:3001 -- node /path/to/symbol-mcp-server/dist/index.js

Or commit a project-level .mcp.json:

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" }
    }
  }
}

Other clients

The same npx command works in any MCP host that starts stdio servers. File locations and formats below follow each client's own documentation.

Cursor: ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in one project.

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" }
    }
  }
}

VS Code: .vscode/mcp.json in the workspace, or the user-level file opened with the command MCP: Open User Configuration. The top-level key is servers, not mcpServers.

{
  "servers": {
    "symbol": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" }
    }
  }
}

Cline: in the Cline panel, open MCP Servers → Configure → Configure MCP Servers and add the server under mcpServers (the Cline CLI reads the same format from ~/.cline/mcp.json).

{
  "mcpServers": {
    "symbol": {
      "command": "npx",
      "args": ["-y", "symbol-mcp-server"],
      "env": { "SYMBOL_NODE_URL": "https://<node-host>:3001" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

On Windows, a client that cannot start npx may need "command": "npx.cmd".

Environment variables