Symbol (XYM)

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 20 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, and is it in sync?" → symbol_node_status {}

{

"summary": "node.test:3001 (friendlyName \"fixture-node\", host \"mainnet-node.example\") on mainnet is healthy and synced.\nSymbol 1.0.3.9, roles Peer/API/Voting; height 5,763,675, finalized 5,763,656 (epoch 4004); 6 peers; latest block 201 s old (not synced above 300 s).", "verdict": "healthy", "sync": { "synced": true, "latestBlockTime": { "utc": "2026-09-10T03:01:38.808Z" }, "ageSeconds": 201, "thresholdSeconds": 300, "checkedAt": { "utc": "2026-09-10T03:05:00.000Z" } }, "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": "chain_tip_age", "status": "ok", "detail": "Latest block (height 5,763,675) is 201 s old (about 3.4 min; warn above 300 s, fail above 900 s).", "hint": null } // … and storage_consistent, finalization_lag and roles ] // … then node, network, chain, storage, peers, time and notes }

verdict folds the seven checks into one word, and sync.synced says whether the node follows the chain (null when that could not be judged). A check that is not ok carries a hint with the next step, and the summary lists it on its own line. A request that fails makes its check unknown and its fields null; the call still answers.

"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- .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:// :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, where symbol_harvesting_status keeps its snapshots; 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:// :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:// :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:// :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:// :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:// :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:// :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:// :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:// :3001" }, "disabled": false, "autoApprove": [] } } }

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

Environment variables

Choosing a node

• Your own node is the best choice. SYMBOL_NODE_URL receives what you look up: addresses, transaction hashes, and the ids of namespaces and mosaics (Privacy Policy has the full list). The reference nodes only receive /node/info and /chain/info requests, never your identifiers.
• A public node works, but its operator can see what you look up. Its access logs can show which accounts, transactions and namespaces were queried, when, and from which IP address. Use a node you trust, or your own node for anything you would rather keep private.
• It must be the REST API of an API node. Most tools read /network/properties, accounts, transactions or blocks. Light REST, a REST with a reduced set of endpoints, is not enough: its README in the Symbol repository (client/rest/README_LIGHT.md in symbol/symbol) lists only `/chain