defi-node-health

DeFi RPC node health, block synchronization, uptime and comparison monitoring with a CLI and Model Context Protocol (MCP) server.

No API key required for your own RPC endpoints. Works with Claude Desktop, Cursor, Windsurf and any MCP client.

Features

• Health checks with latency and current block height

• eth_syncing progress and reference-node block lag detection

• Client version, chain ID, network ID and peer count

• Bounded watch sessions with availability and status-change reporting

• Side-by-side comparison of up to 20 RPC endpoints

• Zero runtime dependencies, TypeScript declarations and offline tests

Related MCP server: Openchainbench

Frequently asked questions

How do I check an Ethereum RPC node in Claude Desktop?

Add this MCP server to claude_desktop_config.json:

{
  "mcpServers": {
    "defi-node-health": {
      "command": "npx",
      "args": ["-y", "defi-node-health"]
    }
  }
}

Then ask: "Check the health of https://ethereum-rpc.publicnode.com".

How do I check whether my node is synchronized?

ALLOW_PRIVATE_RPC=1 defi-node-health sync --rpc http://127.0.0.1:8545

For a real block-lag measurement, provide a trusted reference:

ALLOW_PRIVATE_RPC=1 defi-node-health sync \
  --rpc http://127.0.0.1:8545 \
  --reference-rpc https://ethereum-rpc.publicnode.com

Without a reference, in_sync only reflects the node's own eth_syncing response; it does not independently prove the node has reached the network tip.

Does defi-node-health need an API key?

No. It uses the RPC endpoint you provide. Public endpoints may enforce their own rate limits. If your provider requires a URL key, keep that URL in your secret manager and never paste it into shared logs or tickets; tool output redacts userinfo, query strings, fragments and token-like path segments.

Can I compare several RPC providers?

ALLOW_PRIVATE_RPC=1 defi-node-health compare \
  --nodes primary=https://ethereum-rpc.publicnode.com,fallback=http://127.0.0.1:8545

The summary includes healthy, degraded and unhealthy counts plus the fastest reachable endpoint.

Can I monitor node uptime?

ALLOW_PRIVATE_RPC=1 defi-node-health uptime --rpc http://127.0.0.1:8545 --checks 10 --interval 5000

Watch sessions are bounded (maxChecks up to 100) so CLI and MCP calls cannot run forever.

Which chains are supported?

Any EVM-compatible JSON-RPC endpoint. Optional public presets are included for Ethereum, BNB Smart Chain, Polygon, Arbitrum, Optimism, Base and Avalanche.

Install and verify

npm install -g defi-node-health
defi-node-health --version

Or run without a global install:

npx defi-node-health --version

CLI quick start

defi-node-health health --rpc https://ethereum-rpc.publicnode.com
defi-node-health info --rpc https://ethereum-rpc.publicnode.com
defi-node-health watch --rpc https://ethereum-rpc.publicnode.com --checks 3 --interval 10000 --stream

Output is JSON. Watch --stream emits one JSON object per check.

MCP tools

Common options include timeoutMs (default 10000) and retries (default 3). Transient HTTP 429/5xx, network failures and malformed transient responses use exponential backoff. Retry-After is honored up to 60 seconds.

Endpoint security

• Loopback, private, link-local and metadata endpoints are blocked by default, including hostnames that resolve to those addresses.

• For a trusted local or private RPC, opt in explicitly with ALLOW_PRIVATE_RPC=1 or allowPrivateRpc: true in code.

• Redirects are disabled by default. If enabled with allowRedirects: true, every redirect target is revalidated and limited to 3 hops.

• Responses are capped at 1 MiB and JSON nesting is capped at 64 levels; oversized responses fail closed.

• Result and error URLs are redacted. Keep provider credentials in your secret manager rather than sharing credential-bearing URLs.

Status semantics

• healthy: RPC responds within maxResponseMs.

• degraded: RPC responds but exceeds the latency threshold.

• unhealthy: RPC request fails or returns an invalid response.

• behind: local block is more than maxBlockLag behind reference.

• ahead: local block is more than maxBlockLag ahead of reference.

Development

npm test

Tests use local mock RPC servers and make no external network requests.

License

MIT