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. This is an independent project with no affiliation to the NEM or Symbol core teams.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add symbol-mcp-server -- npx -y symbol-mcp-server@0.10.2在終端機中執行。
{ "mcpServers": { "symbol-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
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. This is an independent project with no affiliation to the NEM or Symbol core teams.
Read-only MCP server exposing the Symbol blockchain REST API as task-level tools
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:
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.
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.
https:// (port 3001 on most public nodes). Public nodes are
listed at https://nodewatch.symbol.tools/.symbol-mcp-server-<version>.mcpb from
Releases.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, where
symbol_harvesting_status keeps its snapshots; the other fields can stay empty.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
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.
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
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 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" }
}
}
}
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".
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./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/info, /node/info, /node/peers, /node/unlockedaccount and /node/server. If a tool
answers does not provide the endpoint … (no such route), see
Troubleshooting.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.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 48-character hex address, a hex public key,
or a namespace name such as alice or alice.pay that carries an address alias; the resolution of
a name is reported in accountResolution and at the start of the summary.
"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_status {} checks the API node, database, storage, clock, finalization lag and the age
of the latest block of the configured node, answers healthy / degraded / unhealthy with the
failing checks, and says whether the node is synced;
→ 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_harvesting_status { "mode": "compare_and_save" } 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; "mode": "compare" looks without storing.
Needs SYMBOL_STATE_DIR; without it the tool reports the current count and says no comparison is
possible. Without a mode the tool answers "how many delegators right now?" and touches no snapshot.
"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.
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 health and
sync 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.
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>]
[--cert <path>]... [--cert-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.
For items 1 to 5 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. Item 6 is the exception: no REST endpoint shows a node's certificate files, so the check reads the files itself and has no MCP tool behind it.
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)
[skip] certificate: no --cert given; pass --cert <path> for each copy of the node certificate to check its expiry
--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. When
/node/info cannot be read at start-up and --cert was given, network is unknown, the five
items that ask the node are skip, certificate is ok, warn or fail, and account is the
argument as given (one longer than 16 characters is cut to its first 8 and …); read the overall
result from verdict (error) and exitCode (3), not from the items. --quiet prints nothing
when the exit code is 0, so cron only mails when there is something to read:
[email protected]
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 \
--cert /path/to/target/nodes/node/cert/node.crt.pem \
--cert /path/to/target/gateways/rest-gateway/api-node-config/cert/node.crt.pem
The entry is broken into lines here only to fit the page: cron has no line continuation, so write it on one line in the crontab.
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_harvesting_status uses (the newest 60 are kept). With --cert it
reads the named files on the machine it runs on; nothing of them is sent anywhere.--quiet. The limit is not
applied when /node/info cannot be read at start-up (see
Node certificate files): no further request is made then, and
the --cert files are only read, up to 1 MiB each.--cert)A node set up with symbol-bootstrap keeps its certificate in two places: the node itself uses
target/nodes/node/cert/node.crt.pem, and the REST gateway has its own copy at
target/gateways/rest-gateway/api-node-config/cert/node.crt.pem. symbol-bootstrap renewCertificates renews the first and does not touch the second. When only the REST gateway's
copy expires, the gateway can no longer talk to the node and /node/health reports
apiNode: down. Pass both files, and check tells you before that happens:
symbol-mcp-server check --cert target/nodes/node/cert/node.crt.pem \
--cert target/gateways/rest-gateway/api-node-config/cert/node.crt.pem
[warn] certificate: warn (copies differ: target/nodes/node/cert/node.crt.pem vs target/gateways/rest-gateway/api-node-config/cert/node.crt.pem)
target/nodes/node/cert/node.crt.pem: ok, expires 2027-01-20T02:11:09.000Z, 370 days left, sha256 0A:1B:2C:…
target/gateways/rest-gateway/api-node-config/cert/node.crt.pem: ok, expires 2026-03-01T02:11:09.000Z, 45 days left, sha256 3D:4E:5F:…
fail when the certificate has expired or has fewer than 7 days left (fixed, not
an option), warn with fewer than --cert-warn-days days left (default 30, a whole number of 1
or more; independent of --warn-days), ok otherwise. Days left are whole days from now to the
certificate's notAfter, rounded down, so the last day counts as 0. A file that holds several
certificates (node.full.crt.pem) is judged by its first one.warn and names the files that differ. A renewal that replaced one copy and
not the other shows up here on the same day, long before the old copy expires. Giving the same
path twice is refused as a usage error, since it would compare the file with itself (paths are
compared as written, after resolving . and ..; a link to the same file, or another spelling
of it on a file system that ignores case, is not noticed).cannot be read (ENOENT),
not a certificate …), and the other files and the other items are still checked.PRIVATE KEY (the label of every PEM
private key) is not parsed and fails with
a private key was passed; pass the certificate (.crt.pem). Any other file that is not a
certificate fails as not a certificate. Either way, the report holds only the path you gave,
the verdict, notAfter (ISO 8601, UTC), the days left, the SHA-256 fingerprint and, in the JSON,
the subject's common name; no other content of a file is printed.--format json adds files: [{ path, status, notAfter, daysLeft, fingerprint256, commonName, reason }] to the certificate item when it ran (reason says why a file could not be used and
is null otherwise; daysLeft is negative once expired).certificate lines are still printed. The
same holds when /node/info cannot be read at start-up (the node does not answer, or answers
with an error): the files are read and judged all the same and the report is printed, with
--quiet too. Its first line says ERROR and gives the network as unknown, the five items
that ask the node are skipped with the reason
/node/info could not be read at start-up, so this check did not run, the certificate item
and the line of each file follow, and stderr says why /node/info could not be read. Without
--cert, only the lines on stderr are printed then. A configuration error (an environment
variable that is missing or not valid, or a node on the wrong network) ends the check before
any file is read.symbol_harvesting_status, in the modes that save
(compare_and_save, save_only), 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).check --cert <path> does, and only the files named there, on the machine it runs on. It opens
no key file on its own, and a PEM private key passed by mistake (a file whose content contains
PRIVATE KEY) is refused without being parsed. Nothing of a file is printed except the
certificate's expiry date, SHA-256 fingerprint and common name, and nothing is sent anywhere.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.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 16 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. In the summary, such text also appears after a
label and in double quotes, with quotes and backslashes escaped as in JSON (untrusted message: "…", friendlyName "…"), so it cannot close the quote and read as the server's own words; alias
and namespace names that fit the namespace grammar stay as they are. Treat all of it as data, not
instructions.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.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
per node, 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.main (every change
lands through a pull request, with linear history) and private vulnerability reporting are enabled.Vulnerability reports: see SECURITY.md.
What the MCP server and its check command send, who receives it, and what stays on your machine.
SYMBOL_NODE_URL and SYMBOL_REFERENCE_NODES.SYMBOL_NODE_URL. It receives what you look up: addresses, transaction hashes,
namespace and mosaic ids, heights and epochs, and the paging, sort order and filter options of
a search. Its operator can see these, together with the time and the IP address they came from.symbol_delegation_diagnose sends the key the node reported for the account back to that same
node, to find the account's delegation request.SYMBOL_REFERENCE_NODES. They receive only /node/info and /chain/info
requests, so their operators see the time and your IP address but nothing you looked up. Every
request, to them and to SYMBOL_NODE_URL, has the header
User-Agent: symbol-mcp-server/<version>.SYMBOL_STATE_DIR: each saved snapshot (symbol_harvesting_status
in mode compare_and_save or save_only, and each run of check) goes into one file per node
there, which holds the node's nodePublicKey and, for the newest 60 snapshots, the time, the
height and the public keys of the unlocked harvesters. The files (their names start with
harvesters-) stay until you delete them; deleting them removes every snapshot the server has
kept.check log a few lines to stderr: the server's start-up line (version,
network, node host and, when set, the time zone, the number of reference nodes and the state
directory), a line for a failed start, for a wrong argument, for an error on the connection to
the MCP host, for an unexpected error or for a time from the node that cannot be shown as a
date, and the diagnostics of check. They write no log file and, apart from the snapshots
above, keep no record of tool calls; what becomes of stderr is decided by the program that
started them (see Troubleshooting).check --cert. The certificate files you name are read on the machine the command runs on,
and nothing of them is stored or sent. The report shows the path you gave and the certificate's
expiry date and SHA-256 fingerprint (with --format json, also its common name), and goes to
stdout; where it goes from there (cron's mail, a log file) is your own setting.npx configurations above run npx at every start) or the bundle is
downloaded, is set by their policies.SECURITY.md instead.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.
npm view symbol-mcp-server dist.attestations prints the attestation URL and the provenance
predicate type of the latest version.npm audit signatures verifies the registry signatures and
provenance attestations of the installed packages.GitHub Releases carry the same package. From 0.8.0 on, each GitHub Release has three files
attached (earlier releases have the first two): symbol-mcp-server-<version>.tgz, byte for byte
the tarball npm serves (its SHA-512 is checked against the registry's dist.integrity),
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), and the Claude Desktop
bundle symbol-mcp-server-<version>.mcpb (next point). The first two 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 first waits
in the npm-publish GitHub Environment until a maintainer approves the run; only then does it
check that the tag matches package.json and the other release files, run lint, typecheck and
tests, and publish. The whole procedure is in docs/RELEASING.md.
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.
symbol_transaction_search may miss old
transactions on such nodes. A public node may also limit how many requests it accepts. The calls
that send the most are symbol_account_rank (up to 50 pages) and symbol_harvesting_income over
a long period (up to 200 pages); use your own node for those.symbol_transaction_get by hash./node/unlockedaccount), not the whole network.symbol_holdings_value multiplies a balance by a unit price the caller passes in; it
does not fetch, check or remember prices, and the result is only as good as that input. Look the
price up first (web search, a price MCP server, or the user) and pass it with priceSource and
priceAsOf. The value is the plain product: no fees, spread or taxes, and no tax lot accounting.symbol_account_rank reads the holder list 100 accounts per
request down to maxRank (at most 5,000, i.e. 50 requests); an account below that gets rank: null
with rankBeyond. Equal balances are ordered by the node and may swap between calls.symbol_harvesting_status 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.truncated; split it with fromHeight/toHeight. Rewards are summed from HarvestFee
receipts, so a node that prunes receipts reports less than the chain holds.fetch field says how the range was read, and only a node that cannot answer about
7 days within SYMBOL_REQUEST_TIMEOUT_MS makes the call fail.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.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 and the age of the latest block in symbol_node_status are measured against
the clock of the machine running this server, which may itself be off.Start-up errors go to stderr as one line starting with symbol-mcp-server failed to start:. MCP
hosts keep stderr in their logs (Claude Desktop: ~/Library/Logs/Claude/mcp*.log on macOS,
%APPDATA%\Claude\logs on Windows), and running the same command in a terminal prints it too.
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 -e SYMBOL_NODE_URL=https://<node-host>:3001 node dist/index.js
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://<testnet-node>: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
SYMBOL_INTEGRATION=1 SYMBOL_NODE_URL=https://<node-host>:3001 SYMBOL_INTEGRATION_MULTISIG_ACCOUNT=<address> npm test # symbol_account_get against a multisig account and its first cosignatory
node scripts/capture-fixtures.mjs https://<node-host>:3001 # refresh test/fixtures/<network>/ from a node
The MCP Inspector gives the server it starts only a few of its own environment variables (PATH,
HOME and the like, the MCP SDK's default) plus the ones it is given, so a variable set in front of
npx does not reach the server. Pass each one with -e KEY=VALUE as above, or enter it in the
Inspector's form; on macOS and Linux, wrapping the server command in env works too.
Design notes: docs/DESIGN-BRIEF.md. Changes: CHANGELOG.md.
Releases: docs/RELEASING.md.
Bug reports, feature requests and pull requests are welcome. See CONTRIBUTING.md
for the development setup, how to add a tool and the design rules; security problems go through
SECURITY.md.
Read-only MCP server exposing the Symbol blockchain REST API as task-level tools
{ "mcpServers": { "symbol-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Symbol 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 Read-only MCP server exposing the Symbol blockchain REST API as task-level tools