Symbol (XYM) 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 20 task-level tools. Instead of mirroring REST endpoints one-to-one, each tool answers a question a person actually asks:

details with decoded messages, mosaic and namespace lookups, fee estimates, address validation, height/epoch/time conversion.

• Account holders: balances with alias names and decimals applied, transaction history and

reference nodes, and above all voting-key expiry: remaining epochs, blocks and days, the estimated expiry date and a recommended renewal window.

• Node operators: node health and sync state, delegated-harvesting status, comparison against

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

listed at https://nodewatch.symbol.tools/.

• Node.js 22 or newer.
• A Symbol REST node reachable over https:// (port 3001 on most public nodes). Public nodes are

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

Shortened. The full README is on GitHub.