Symbol MCP Server

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, 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.

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. 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 <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

Choosing a node

• Your own node is the best choice. Every call sends the addresses, public keys, hashes and namespace names you ask about to SYMBOL_NODE_URL. 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.
• Finding one: https://nodewatch.symbol.tools/ lists mainnet and testnet nodes with their height and version. Pick an API node that is at the current height, runs the majority version and answers over https:// (usually port 3001). Set SYMBOL_NETWORK to make start-up fail if the node turns out to be on the other network, and try it with SYMBOL_NODE_URL=https://<node-host>:3001 npx -y symbol-mcp-server check.

Tools

All 22 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 <hash> go through?" → symbol_transaction_status { "transactionHashes": ["<hash>"] } 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.

"Where does NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY rank by XYM holdings? Who are the top 10?" → symbol_account_rank { "account": "NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY", "top": 10 } Reads the holder list ordered by balance 100 accounts at a time until the account turns up (or maxRank, default 1000, is reached), and returns its balance, share of supply and rank together with the top 10 holders and their combined share. All shares are computed by the server in integer arithmetic; the top of the list is usually exchanges and the foundation, and the tool labels nobody.

"If XYM is 12.34 yen, how much are my holdings worth? NCV5HRBSFEGTPNBIUPBVAGWXWXZ43C4TNOQUYUY" → symbol_holdings_value { "account": "NCV5HR…", "unitPrice": "12.34", "currency": "JPY" } Reads the balance and multiplies it by the price in integer arithmetic: 53,321,140 JPY for 4,321,000 XYM, with the exact product alongside. The price comes from the caller. This server never contacts a price API (it talks to SYMBOL_NODE_URL only), so when you ask "what are my holdings worth right now?" the flow in Claude Desktop is: the model looks the price up first (a web search, another MCP server that serves prices, or you type it in), then calls this tool with unitPrice, currency and, ideally, priceSource / priceAsOf so the answer says where and when the price was observed. The model is told not to multiply balance by price itself.

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 the questions that are easy to mix up: harvest income, voting keys, node sync versus health versus version, whether a transaction went through; use the returned numbers as they are). Tools that answer neighbouring questions point to each other in their descriptions.

CLI: monitoring from cron

The same binary has a one-shot check subcommand that needs no MCP client. It judges the node with the tools above, prints one report and exits non-zero when something is wrong:

symbol-mcp-server check [--account <address|publicKey|namespace>] [--warn-days <n>]
                        [--format text|json] [--quiet]

It reads the same environment variables as the server (SYMBOL_NODE_URL is required; SYMBOL_TIMEZONE, SYMBOL_REFERENCE_NODES and SYMBOL_STATE_DIR are optional) and needs Node.js 22 or newer. Started without arguments the binary is still the MCP server, unchanged.

The judgments are the tools' own; the check only reads their output, and the hint printed under a warn or fail line is the tool's text. A tool that fails (for example an HTTP error) fails its item and the others still run.

Text output (the default; illustrative values):

symbol check: WARN (node.example:3001, mainnet, 2026-01-15T07:00:03+09:00)
[ok] node_health: healthy (finalization lag 12 blocks)
[ok] version_drift: ok. node.example:3001 runs 1.0.3.9; majority of 24 sampled nodes runs 1.0.3.9; 0% run something newer.
[ok] harvester_watch: 18 unlocked harvesters on node.example:3001, unchanged since 2026-01-14T07:00:02+09:00 (2026-01-13T22:00:02.000Z). Snapshot saved (31 stored).
[warn] voting_key_status: active key 0A1B2C3D… expires in about 12.4 days (epoch 4321, estimated 2026-01-27T16:40:00+09:00 (2026-01-27T07:40:00.000Z))
  hint: Active voting key 0A1B2C3D… expires at epoch 4321 in about 12.4 days (...) and no successor key is registered.
[ok] finality_participation: epoch 4290: participated (signed prevote and precommit)

--format json prints the same report as one JSON document: { verdict, exitCode, node: { host, network }, checkedAt, checks: [{ id, status, detail, hint }], warnDays, account }, with verdict one of ok, warn, fail, error (exit code 3) and account the resolved address. --quiet prints nothing when the exit code is 0, so cron only mails when there is something to read:

MAILTO=you@example.com
0 7 * * * SYMBOL_NODE_URL=https://node.example:3001 SYMBOL_STATE_DIR=/var/lib/symbol-mcp-server \
  npx --yes symbol-mcp-server check --account NXXX... --warn-days 14 --quiet

• The check sends no notification. It writes to stdout and stderr and sets the exit code; mail is cron's job (MAILTO). It contacts SYMBOL_NODE_URL and the SYMBOL_REFERENCE_NODES, nothing else, and is as read-only as the server. With SYMBOL_STATE_DIR set, every run appends one snapshot to the file symbol_harvester_watch uses (the newest 60 are kept).
• The whole run is limited to 120 seconds. At the limit the remaining items are skipped, the reason goes to stderr, and the result is WARN at best, printed even with --quiet.
• A typo in the subcommand name is an unknown argument of the server and exits with 2, as before.

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, metadata values, alias names and what a node reports about itself (friendly name, host name, status and version strings) are written by third parties. They are exposed under names that make this obvious (messageText) and made one line: tabs and line breaks become a space, so words stay apart, and runs of spaces become one. Every other control and invisible format character is stripped (zero-width and bidi characters, soft hyphens, and the tag characters U+E0000 to U+E007F that people cannot see but models can read), and length is capped without splitting a character. Variation selectors are kept, so emoji and ideograph variants survive; emoji joined by a zero-width joiner come out as separate emoji. The 17 tools that show such text report in invisibleCharactersRemoved how many characters were removed from it, and when any were, the summary ends with a line saying so. Treat all of it 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 applied while the body streams in (a larger declared Content-Length is refused unread), at most 4 concurrent requests, and schema validation of every response. Redirects are never followed: a node that answers with HTTP 3xx gets an error, and the address it points to is not contacted. Request paths carry plain identifiers only.
• Repository settings. CodeQL code scanning, secret scanning with push protection, Dependabot (security updates and grouped monthly version updates), branch protection on main (every change lands through a pull request, with linear history) and private vulnerability reporting are enabled.

Vulnerability reports: see SECURITY.md.

Release integrity

• Published from CI, with provenance. Every npm release is built and published by the GitHub Actions workflow release.yml through npm trusted publishing (OIDC). There is no npm token, neither on a maintainer's machine nor in the repository secrets. Each version carries a provenance attestation that links it to the source commit and the workflow run that built it.

• Check it yourself.

  • The package page on npmjs.com shows a Provenance section with the commit and the workflow run.
  • npm view symbol-mcp-server dist.attestations prints the attestation URL and the provenance predicate type of the latest version.
  • In a project that installs it, npm audit signatures verifies the registry signatures and provenance attestations of the installed packages.

• GitHub Releases carry the same package. Each GitHub Release has two files attached: symbol-mcp-server-<version>.tgz, byte for byte the tarball npm serves (its SHA-512 is checked against the registry's dist.integrity), and symbol-mcp-server-<version>.tgz.sigstore.json, npm's SLSA provenance for that tarball as a Sigstore bundle (its subject is checked to be the tarball's SHA-512). Both are collected by scripts/release-assets.sh. To verify a downloaded pair with the GitHub CLI:

  gh attestation verify symbol-mcp-server-<version>.tgz \
    --bundle symbol-mcp-server-<version>.tgz.sigstore.json \
    --repo inotakeh/symbol-mcp-server --digest-alg sha512
  

  --digest-alg sha512 is needed because npm's provenance names the tarball by its SHA-512.

• The Claude Desktop bundle is built from that same tarball. symbol-mcp-server-<version>.mcpb is made by scripts/build-mcpb.sh from the checked npm tarball above plus the production dependencies installed with npm ci --omit=dev from the lockfile of that release; nothing else is compiled or downloaded. The release workflow attaches a GitHub build provenance attestation to it (gh attestation verify … --repo inotakeh/symbol-mcp-server, see Install).

• Who can release. Only maintainers create release tags (v1.2.3). The workflow checks that the tag matches package.json, runs lint, typecheck and tests, and then waits in the npm-publish GitHub Environment until a maintainer approves the run. The whole procedure is in docs/RELEASING.md.

Supported networks

The network is detected from the node at start-up. Any other generation hash seed (private networks, NEM NIS1) is rejected. Nodes of both networks are listed at https://nodewatch.symbol.tools/; see Choosing a node.

Limitations

Documentation truncated — see the full README on GitHub.