@verusidx/chain-mcp

Foundation MCP server for the Verus blockchain. Handles chain discovery, daemon management, health checks, and raw transaction operations. All other verusidx MCP servers depend on this one.

Setup

Add to your MCP client config (e.g., Claude Code claude_desktop_config.json):

{
  "mcpServers": {
    "verusidx-chain": {
      "command": "npx",
      "args": ["-y", "@verusidx/chain-mcp"],
      "env": {}
    }
  }
}

Alternative: local install. If you prefer a pinned version or offline use, install into a project directory with npm install @verusidx/chain-mcp (or pnpm add / yarn add) and point your config at the local path instead of using npx.

Environment Variables

| Variable | Default | Description | |---|---|---| | VERUSIDX_READ_ONLY | false | Set to true to disable write tools (verusd, stop, sendrawtransaction, signrawtransaction). Read tools and refresh_chains remain available. | | VERUSIDX_DATA_DIR | OS default | Override the chain data directory for discovery. Defaults to ~/Library/Application Support/Komodo (macOS), ~/.komodo (Linux), %AppData%\Komodo (Windows). | | VERUSIDX_EXTRA_CHAINS | — | Add remote daemons. Format: name:host:port:user:pass, comma-separated. Example: remote-vrsc:192.168.1.50:27486:rpcuser:rpcpass | | VERUSIDX_BIN_PATH | — | Directory containing the verusd binary. If not set, searches PATH then OS-specific default locations. | | VERUSIDX_AUDIT_LOG | true | Set to false to disable audit logging of write operations. | | VERUSIDX_AUDIT_DIR | OS default | Custom directory for audit log files. Defaults to ~/.config/verusidx-mcp/audit (Linux), ~/Library/Application Support/verusidx-mcp/audit (macOS). |

Read-Only Mode

Set VERUSIDX_READ_ONLY=true to run in read-only mode. This is useful for monitoring, research, or exploration — no blockchain state can be modified. Write tools are not registered (they won't appear in the tool list). If a stale client attempts to call a write tool anyway, it receives a WRITE_DISABLED error.

You can set read-only mode independently per MCP server. For example, keep chain-mcp read-write (for refresh_chains and daemon management) while running send-mcp in read-only mode.

Tools

Always available

| Tool | Description | |---|---| | getinfo | Get blockchain and node info (version, block height, connections, sync status) | | getwalletinfo | Get wallet balances (confirmed, unconfirmed, immature, reserve currencies) | | help | Get daemon documentation for any RPC command | | getblockcount | Get current block height (lightweight) | | getcurrency | Get full definition and state of a currency (reserves, weights, prices, fees) | | status | Check registry freshness and daemon reachability | | refresh_chains | Re-run chain discovery and rewrite the registry file |

Write tools (disabled in read-only mode)

| Tool | Description | |---|---| | stop | Stop a running daemon (terminates the process for ALL clients) | | verusd | Start a Verus daemon instance (spawns detached process) | | sendrawtransaction | Broadcast a signed raw transaction to the network | | signrawtransaction | Sign inputs of a raw transaction (for multisig workflows) |

Chain Registry

On first run, call refresh_chains to discover local chains. The server scans for .conf files in the chain data directory and PBaaS directory, checks which daemons are running, and writes a registry file (chains.json). All other verusidx MCP servers read this file to know what chains are available.

Every tool that talks to a daemon requires a chain parameter (e.g., "VRSC", "vrsctest"). There is no default chain — the agent or user always specifies which chain to operate on.

Audit Logging

All write operations (stop, verusd, sendrawtransaction, signrawtransaction, refresh_chains) are logged to date-stamped JSONL files in the audit directory. Each entry records the tool name, chain, parameters, result, and success status. Logs are append-only with 0600 permissions.

Requirements

• Node.js >= 18.0.0
• At least one Verus daemon installed (for verusd tool) or already running (for RPC tools)