MCP Documentation

Model Context Protocol server for LLM agent integration with Bitcoin on-chain metrics. Provides access to 45 metrics across 7 categories.

Connection

Endpoint	https://btc-indexer.bitcoinmetrics.net/mcp
Transport	Streamable HTTP (stateless mode)
Authentication	`X-Api-Key` header (same keys as REST API)

Client Configuration

{
  "mcpServers": {
    "btc_indexer": {
      "type": "streamable-http",
      "url": "https://btc-indexer.bitcoinmetrics.net/mcp",
      "headers": {
        "X-Api-Key": "btci_your_key"
      }
    }
  }
}

Available Tools

TOOL list_metrics

List all 45 available Bitcoin on-chain metrics across 7 categories, with their tier, quality, and descriptions.

No parameters required.

Response

[
  {
    "id": "market/nvt",
    "category": "market",
    "metric": "nvt",
    "value_type": "scalar",
    "intervals": ["24h", "1w", "1month"],
    "aggregation": "last",
    "tier": "core",
    "quality": "exact",
    "name": "NVT Ratio",
    "description": "Network Value to Transactions ratio...",
    "history_requirement": "90d",
    "coverage_window": "180d",
    "interpretation_notes": "Both components are accurate within the retained window."
  }
]

id is the precomputed "category/metric" identifier — copy it verbatim into get_metric calls and into any client-side metric registry. coverage_window tells you how far back data is reliably available (typical: 180d) — bound any historical analysis accordingly.

TOOL get_metric

Fetch time-series data for a Bitcoin on-chain metric.

Parameters

Param	Type	Required	Description
category	string	yes	Metric category (market, supply, addresses, transactions, mining, fees, blocks)
metric	string	yes	Metric name (e.g. nvt, price_usd, mvrv)
since_date	string	no	Start date (YYYY-MM-DD). Default: 1 year ago
until_date	string	no	End date (YYYY-MM-DD). Default: yesterday
interval	string	no	Aggregation interval: 24h, 1w, or 1month. Default: 24h

Response — Scalar metric

[
  { "t": 1704067200, "v": 50.3 },
  { "t": 1704153600, "v": 51.1 }
]

Response — Complex metric (HODL waves)

[
  {
    "t": 1704067200,
    "o": {
      "lt_1d": 100.0, "1d_1w": 200.0, "1w_1m": 300.0,
      "1m_3m": 400.0, "3m_6m": 500.0, "6m_1y": 600.0,
      "lth_supply": 1000.0, "sth_supply": 800.0
    }
  }
]

TOOL get_market_overview

Get a snapshot of latest Bitcoin on-chain metrics grouped by tier.

Parameters

Param	Type	Default	Description
include_experimental	boolean	false	Include experimental metrics in response

Response

{
  "as_of": "2026-04-10",
  "core": {
    "price_usd": 84250.0,
    "nvt": 48.5,
    "market_cap": 1680000000000.0,
    "count": 312450.0,
    "hash_rate_mean": 845.0,
    "mvrv": 1.42,
    "nupl": 0.31
  },
  "experimental": {}
}

TOOL get_sync_status

Check Bitcoin indexer sync progress.

No parameters required.

Response

{
  "last_indexed_height": 890123,
  "blocks_behind": 3,
  "updated_at": "2026-04-10T14:30:00Z"
}

Errors

When a tool fails, the MCP response sets isError: true and the content text is a JSON-encoded body in the form {"error":{"code":"...","message":"..."}}. Codes are stable strings agents can branch on.

Code	Tool	Description
unknown_metric	`get_metric`	Unknown `category/metric` combination — call `list_metrics` for valid keys.
metric_disabled	`get_metric`	Metric is temporarily disabled by the indexer; pick a different metric for now.
invalid_argument	`get_metric`	Bad date format, unsupported interval, or date range exceeds server limits.
no_data	`get_market_overview`	Indexer has no data yet (cold start) — try again after the first daily aggregate runs.

Example error body

{ "error": { "code": "unknown_metric", "message": "Unknown metric: market/foo" } }

Notes

All tools are read-only and idempotent
Same API key authentication as REST API
For REST endpoint documentation, see API Documentation