Symbol
Read-only MCP server for the Symbol blockchain (XYM): node health, harvesting, voting keys.
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.
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 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
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
From the project's README.