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, with a one-to-three-line summary first. 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.

Requirements

• Node.js 20 or newer.

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

Related MCP server: Algorand MCP Server

Install

From npm (recommended):

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. The binary takes no other flags: 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 0.1.0: 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" }
    }
  }
}

Environment variables

Tools

All 20 tools are read-only (readOnlyHint: true) and are listed in a fixed order. Arguments are identifiers only, never URLs. Every account argument (and the address of symbol_transaction_search) takes a base32 address, a hex public key, or a namespace name such as alice or alice.pay that carries an address alias; the resolution is reported in accountResolution and at the start of the summary.

Example questions

"When does the voting key of NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY expire, and when should I renew it?" → symbol_voting_key_status { "account": "NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY" } Returns each key's startEpoch/endEpoch, the expiry height (endEpoch - 1) × votingSetGrouping, remaining epochs, blocks and days, an estimated expiry date based on the measured average block time, the renewal window, free slots (expired keys still occupy slots) and whether the balance meets minVoterBalance.

"Show me alice's account." → symbol_account_get { "account": "alice" } The namespace alice is resolved through the node to its address alias (a missing, expired, mosaic-aliased or alias-less namespace is an error with a hint); the answer starts with alice → NCV5… and carries the resolution in accountResolution. Works for every account argument.

"How much XYM does NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY hold?" → symbol_account_get { "account": "NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY" } Returns every mosaic with alias (symbol.xym), amount (decimals applied) and rawAmount.

"Show the last 20 transfers involving that account, then the details of the newest one." → symbol_transaction_search { "address": "NCV5HR…", "type": "transfer", "pageSize": 20 } → symbol_transaction_get { "transactionHash": "<hash from the list>" } The list gives hashes, dates, counterparties and message previews; the second call adds fees, full decoded messages and inner transactions.

"Is my node behind?" → symbol_node_status {} checks the age of the latest block on the configured node; → symbol_network_compare {} reports how many blocks it trails SYMBOL_REFERENCE_NODES.

"How much did NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY earn from harvesting in August 2026?" → symbol_harvesting_income { "account": "NCV5HR…", "fromDate": "2026-08-01", "toDate": "2026-08-31" } Resolves the dates to block heights, reads every HarvestFee receipt addressed to the account and sums them as exact integers: total XYM, harvester versus beneficiary share, and one row per day. Nothing is left for the model to add up.

"I just announced my voting key link. Did transaction FAEEB042… go through?" → symbol_transaction_status { "transactionHashes": ["FAEEB042…"] } Answers confirmed (with the height), unconfirmed, partial (aggregate bonded waiting for cosignatures), failed (with the node's code such as Failure_Core_Insufficient_Balance and its meaning) or not_found. Always an array, up to 20 hashes per call.

"Was my voting node NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY actually able to vote last week?" → symbol_finality_participation { "account": "NCV5HR…", "epochs": 14 } Reads the finalization proof of the latest finalized epoch and the 13 before it (an epoch is votingSetGrouping blocks, about 12 hours on mainnet) and reports per epoch whether one of the account's voting keys is among the signers of both stages, how many voters signed, and a warning if the current epoch was missed or no key covers it.

"I think my delegated harvesting is not working. Have a look at NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY." → symbol_delegation_diagnose { "account": "NCV5HR…" } Runs eleven checks in a fixed order (existence, balance limits, importance, the three key links, node key versus the configured node, unlocked on that node, account type, recent harvested blocks, the delegation request transfer) and answers active, not_active (with the failing step and a hint) or cannot_verify (the account delegates to a node other than SYMBOL_NODE_URL, so the node side cannot be checked).

"Is my node healthy, and is its version behind?" → symbol_node_health {} checks the API node, database, storage, clock and finalization lag of the configured node and answers healthy / degraded / unhealthy with the failing checks; → symbol_version_drift {} compares the node version with its peers and the reference nodes and answers ok / behind / far_behind. Both are the first things to look at after a node OS migration.

"Have my delegators come back after the migration?" → symbol_harvester_watch {} compares the harvesters unlocked on the node right now with the last stored snapshot (added and removed keys, count delta, 30-day min / max / average) and stores today's list for the next check. Needs SYMBOL_STATE_DIR; without it the tool reports the current count and says no comparison is possible.

More cases, with the exact arguments expected for each, are in evals/cases.json.

Prompts

Two MCP prompts (prompts/list) bundle the tool calls a node operator repeats. Both take one argument, account: the 39-character base32 address of the voting / harvesting account. The prompt text contains no addresses, hosts, keys or dates of its own.

The server also sends short instructions at initialize time (read-only, account formats, which tool answers harvest-income and voting-key questions, use the returned numbers as they are).

Security

• Read-only. No tool signs, builds or announces transactions. No argument accepts a private key, mnemonic or token. Nothing is stored between calls, except that symbol_harvester_watch keeps its per-node snapshot of unlocked harvester public keys, heights and times under SYMBOL_STATE_DIR when that variable is set (no secrets; delete the file to start over).

• Fixed destinations. The server contacts only SYMBOL_NODE_URL and, for symbol_network_compare and symbol_version_drift, the hosts listed in SYMBOL_REFERENCE_NODES. Tools never take a URL as an argument, so a model cannot redirect requests. There is no telemetry.

• Untrusted chain data. Transfer messages, node friendly names, host names and alias names are written by third parties. They are exposed under names that make this obvious (messageText), control and bidi characters are stripped, and length is capped. Treat them as data, not instructions.

• Fail loudly. A network mismatch (SYMBOL_NETWORK versus the node), an unreachable node or an unexpected response shape is an error with a recovery hint, never a silent fallback to another network. Stack traces and raw HTTP bodies are never returned to the model.

• Request hygiene. Per-request timeout, User-Agent, a 5 MB response cap, at most 4 concurrent requests, and schema validation of every response.

Vulnerability reports: see SECURITY.md.

Supported networks

The network is detected from the node at start-up. Any other generation hash seed (private networks, NEM NIS1) is rejected. Node availability changes over time; pick a current one from https://nodewatch.symbol.tools/.

Limitations

• Node history. Results come from the configured node. Nodes that prune transaction history return only what they still hold, so symbol_transaction_search may miss old transactions on such nodes.

• Future dates are estimates. Expiry dates for voting keys, namespaces and mosaics, and any future height or epoch, are projected from the measured average block time over the last 10,000 blocks (about 30 s on mainnet) and are flagged as estimates.

• Encrypted messages are not decrypted; they are reported as encrypted.

• Page size is 10 to 100, because catapult-rest coerces smaller pages to 10.

• Confirmed transactions only in search. Unconfirmed and partial transactions are visible through symbol_transaction_get by hash.

• Harvesting status covers the configured node (/node/unlockedaccount), not the whole network.

• Harvester history is local. symbol_harvester_watch compares against snapshots it wrote itself under SYMBOL_STATE_DIR; another machine, a deleted file or a changed node key (a new node.key.pem after a migration) starts a new baseline. Repeated calls on the same day add repeated snapshots; only the newest 60 are kept.

• Harvest income reads at most 20,000 statements per call (200 pages of 100). A longer period comes back truncated; split it with fromHeight/toHeight. Rewards are summed from HarvestFee receipts, so a node that prunes receipts reports less than the chain holds.

• Finality participation reads the proofs the node holds. unavailable means the node has no proof for that epoch (not finalized yet, or outside the history it keeps), not that the account did not vote. The server does not know how many voters are registered, so signatureCount can only be compared with an external list such as nodewatch.

• Version drift is sampled, not surveyed. symbol_version_drift sees the peers the configured node currently knows plus the reference nodes, not the whole network; the full picture is on nodewatch. Clock skew in symbol_node_health is measured against the clock of the machine running this server, which may itself be off.

• Mainnet and testnet only. No transaction building, signing or announcing, by design.

• The URL is used as given. The server does not switch ports or schemes on its own; if a node only serves port 3000 over http, it cannot be used unless it is on localhost.

Development

npm ci
npm run lint && npm run typecheck && npm test
npm run build
SYMBOL_NODE_URL=https://<node-host>:3001 node dist/index.js
npx @modelcontextprotocol/inspector node dist/index.js
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://sym-test-01.opening-line.jp:3001 npm test   # live-node tests
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://<node-host>:3001 SYMBOL_INTEGRATION_ACCOUNT=<address> npm test   # account tools against a specific account
node scripts/capture-fixtures.mjs https://<node-host>:3001   # refresh test/fixtures/<network>/ from a node

Design notes: docs/DESIGN-BRIEF.md. Changes: CHANGELOG.md.

License

MIT