chunknet/mcp-server

Chunk MCP Server

Production-ready MCP server exposing Chunk MedianFeeds tools over stdio.

• Network: Chunk testnet (default RPC: https://rpc.chunknet.org)
• Contract: MedianFeeds (default): 0x78D02A47fA898ffF4B37A9B414Eace5eed3e7fAD

Requirements

• Node.js 18+ (ESM modules)

Quickstart

• Install
  • cd mcp-server
  • npm install
• Build
  • npm run build
• Run (stdio transport)
  • npm start

Configuration

• Environment variables
  • CHUNK_RPC — JSON-RPC endpoint (default: https://rpc.chunknet.org)
  • CHUNK_MEDIAN_ADDR — MedianFeeds contract address (default: 0x78D02A47fA898ffF4B37A9B414Eace5eed3e7fAD)
  • METRICS_CACHE_TTL_MS — metrics cache TTL in milliseconds (default: 30000)

Production .env (overrides optional)

CHUNK_RPC=https://rpc.chunknet.org
CHUNK_MEDIAN_ADDR=0x78D02A47fA898ffF4B37A9B414Eace5eed3e7fAD
METRICS_CACHE_TTL_MS=30000

Notes: You can omit .env entirely — these are the built-in defaults.

Tools

• list_metrics — List metric definitions from MedianFeeds
  • Args: { chain?, rpcUrl?, contractAddress?, currency?, tagIncludes?, nameContains?, limit?, offset? }
• quote_metrics — Get last quotes for given metric names
  • Args: { names: string[], chain?, rpcUrl?, contractAddress?, format?: 'raw'|'int'|'decimal'|'all', decimals?: number }
• get_signed_root — Get current signed Merkle tree root (epoch)
  • Args: { chain?, rpcUrl?, contractAddress? }
• get_metrics_count — Total metrics count
• has_metric — Check if a metric exists by name
• get_metrics_map — Mapping name -> id (index-based)
• quote_by_ids — Quote metrics by numeric ids
  • Args: { ids: number[], chain?, rpcUrl?, contractAddress?, format?, decimals? }
• quote_metrics_at_block — Quote metrics at specific block number
  • Args: { names: string[], blockNumber: number, chain?, rpcUrl?, contractAddress?, format?, decimals? }
• quote_metrics_at_epoch_end — Quote metrics at the end of an epoch
  • Args: { names: string[], epochDuration?: number, epochId?: number, chain?, rpcUrl?, contractAddress?, format?, decimals? }
• quote_metrics_at_timestamp — Quote metrics at specific UNIX timestamp (seconds)
  • Args: { names: string[], timestamp: number, chain?, rpcUrl?, contractAddress?, format?, decimals? }
• get_health — RPC health info { chainId, blockNumber }
• check_staleness — Check if metrics are stale w.r.t maxAgeSeconds
• check_thresholds — Threshold checks for rules of form { name, op: 'lt'|'lte'|'gt'|'gte'|'eq'|'neq', value: string|number }

Formatting

• Raw values are returned as on-chain 2**112-scaled integers.
• Use format: 'decimal' and decimals to get human-friendly strings with rounding.

Resources

• chunk://median/{chain}/metrics — JSON array of metrics for a chain (chunk supported)
• chunk://median/{chain}/metric/{name} — JSON object with the latest quote for a metric

Subscriptions

• The server registers resources.subscribe capability.
• On epoch changes, resources/updated notifications are sent for subscribed URIs.

Client Example (Node.js)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/server.js'],
  env: process.env,
});

const client = new Client({ name: 'chunk-mcp', version: '0.1.0' });
await client.connect(transport);

const list = await client.callTool({ name: 'list_metrics', arguments: { limit: 5 } });
const names = list.structuredContent.metrics.map(m => m.name).slice(0, 2);
const quotes = await client.callTool({ name: 'quote_metrics', arguments: { names, format: 'decimal', decimals: 6 } });
console.log(quotes.structuredContent.quotes);

await client.close();

Claude Desktop (MCP) configuration (example)

• Configure a stdio MCP server:

{
  "mcpServers": {
    "chunk-mcp": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "CHUNK_RPC": "https://rpc.chunknet.org",
        "CHUNK_MEDIAN_ADDR": "0x78D02A47fA898ffF4B37A9B414Eace5eed3e7fAD"
      }
    }
  }
}

Operational Notes

• Timeouts and RPC limits depend on your provider.
• Handle network errors and transient failures with retries on the client side.
• For production, pin a stable RPC endpoint and contract address.

Project Structure

• src/server.js — source (ESM)
• dist/server.js — bundled build (after npm run build)
• No tests are included in this directory by design.