MCP Server for AI Agents

Blocklens provides an MCP server that lets AI agents query on-chain analytics directly during conversations. Instead of copy-pasting API responses, your agent discovers available tools and calls them autonomously.

What is MCP?

Model Context Protocol (MCP) is an open standard created by Anthropic that defines how AI applications connect to external data sources and tools. Think of it as a universal adapter — any MCP-compatible agent (Claude, Cursor, Windsurf, etc.) can connect to any MCP server without custom integration code.

With MCP, the agent doesn't just read data — it can discover what tools are available, understand their parameters, and call them with the right arguments. This makes interactions far more natural than crafting API calls manually.

Remote Access (No Install Required)

The fastest way to connect is via our hosted MCP endpoint — no packages to install, no local setup.

Claude.ai

Go to Settings → Connectors
Click + to add a new connector
Paste the URL: https://mcp.blocklens.co
Leave Client ID and Client Secret empty → click Add
Authorize with your API key when prompted

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.blocklens.co"]
    }
  }
}

ChatGPT

Enable Developer Mode: Settings → General → Developer Mode
Go to Settings → Developer → MCP Servers
Click Add Server, enter name "Blocklens" and URL: https://mcp.blocklens.co
Authorize with your API key when prompted

Cursor / Windsurf

Open Settings → MCP Servers
Add a remote server with URL: https://mcp.blocklens.co
Authorize with your API key when prompted

For Cursor, you can also add to .cursor/mcp.json:

{
  "mcpServers": {
    "blocklens": {
      "url": "https://mcp.blocklens.co"
    }
  }
}

Any MCP HTTP Client

POST to https://mcp.blocklens.co using the Streamable HTTP transport. The server supports the full MCP protocol — tool discovery, invocation, and streaming responses.

No install needed

The remote endpoint provides the same 19 tools as the npm package. It works in the browser, requires no local dependencies, and supports demo mode out of the box.

Authentication

The MCP server supports two access modes:

Free Access (No API Key)

Connect without any credentials to access free-tier metrics: prices, holder supply, valuation, ETF aggregate, coindays, and blockchain data. Up to 60 days of history.

Full Access (With API Key)

Unlock all metrics including Pro and Enterprise tiers. When you first connect, a Blocklens authorization page will appear where you enter your API key. This uses a secure OAuth flow — no Client ID or Secret needed.

Get your API key at blocklens.co/api-mcp.

Why Blocklens + MCP?

Blocklens provides native MCP support for on-chain analytics, letting AI agents query metrics directly without custom integration.

What this means in practice:

Real-time on-chain queries — Ask your AI agent "Is Bitcoin overvalued right now?" and it will call get_holder_valuation to check MVRV, realized cap, and more
No manual API work — The agent discovers tools automatically and formats responses for you
Research at conversation speed — Chain multiple queries together: check price, then supply, then profitability, all in one conversation
Automated reporting — Have your agent generate weekly on-chain health reports with live data

Local Install (Alternative)

See Remote Access for the simplest setup — no packages or local config needed.

Install

npm install -g blocklens-mcp-server

Claude Desktop

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["-y", "blocklens-mcp-server"],
      "env": {
        "BLOCKLENS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

After saving, restart Claude Desktop. You should see "blocklens" listed under available MCP tools.

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["-y", "blocklens-mcp-server"],
      "env": {
        "BLOCKLENS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Demo Mode (No API Key)

You can try the MCP server without an API key. In demo mode:

Works: list_metrics, search_metrics, get_metric, get_categories, and data endpoints with up to 60 days of history for basic (grade 0) metrics
Requires API key: Profit metrics (SOPR, realized P/L), extended history, enterprise-tier metrics

To run in demo mode, simply omit the BLOCKLENS_API_KEY from your config:

{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["-y", "blocklens-mcp-server"]
    }
  }
}

Available Tools

The MCP server exposes 19 tools that cover the full Blocklens analytics suite: market data, holder supply, valuation, profitability, age cohorts, UTXO history, coin days, ETF analytics, blockchain stats, cycle boundaries, and chart rendering. Built on a unified TypeScript codebase.

Tier Requirements

Tier	Tools
Free	`list_metrics`, `search_metrics`, `get_metric`, `get_categories`, `get_latest_metrics`, `get_prices`, `get_holder_supply`, `get_holder_valuation`, `get_etf_data`, `get_coindays`, `get_blockchain`, `get_cycle_boundaries`
Pro	`get_holder_profit`, `get_cohort_metrics`, `get_utxo_history`
Pro	`get_dat_entity`
Depends on metric	`render_chart` — free metrics render without a key; Pro/Enterprise metrics require the corresponding tier

`list_metrics`

Free

List all available on-chain metrics with descriptions, categories, and tier requirements.

Parameters: None

Use case: Start here to discover what data is available. Returns the full catalog with metric IDs you'll need for other tools.

Example response (abbreviated):

[
  {
    "id": "price",
    "name": "BTC Price",
    "category": "price",
    "unit": "USD",
    "endpoint": "prices",
    "grade": 0
  },
  {
    "id": "lth_supply",
    "name": "LTH Supply",
    "category": "supply",
    "unit": "BTC",
    "endpoint": "holder/supply",
    "grade": 0
  },
  {
    "id": "funding_binance",
    "name": "Binance Funding Rate",
    "category": "exchanges",
    "endpoint": "funding/exchange",
    "grade": 1,
    "params": { "exchange": "binance" },
    "params_schema": {
      "exchange": {
        "type": "string",
        "required": true,
        "description": "Exchange identifier",
        "values_endpoint": "/v1/funding/exchanges"
      }
    }
  }
]

Parameterized metrics

Some metrics require additional parameters (e.g., exchange, ticker, id). Check the params field for default values and params_schema for parameter descriptions and available values endpoints.

`get_prices`

Free

Get daily OHLC prices (open/high/low/close in USD), market cap, and 24h trading volume.

Parameter	Type	Default	Description
`symbol`	string	`"BTC"`	Cryptocurrency symbol
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`). Overrides `days`.
`end_date`	string	—	End date (`YYYY-MM-DD`). Defaults to today.

Use case: Price context for any analysis. Pair with valuation metrics to assess whether current price is justified by on-chain fundamentals.

`get_holder_supply`

Free

Get the LTH/STH supply breakdown: Long-Term Holder supply (held >155 days), Short-Term Holder supply (held <155 days), and total circulating supply. All values in BTC.

Parameter	Type	Default	Description
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Track accumulation and distribution. Rising LTH supply = conviction / accumulation. Rising STH supply = new money entering / potential distribution ahead.

`get_holder_valuation`

Free

Get Bitcoin valuation metrics: Realized Cap, Realized Price, LTH/STH Realized Cap and Price, MVRV ratio, and Unrealized P/L.

Parameter	Type	Default	Description
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Core valuation framework. MVRV > 3.5 historically signals overheating; MVRV < 1 signals undervaluation. Compare LTH vs STH realized prices to gauge market structure.

`get_holder_profit`

Pro

Get Bitcoin profitability metrics: LTH/STH Realized P/L (USD) and SOPR (Spent Output Profit Ratio). Requires Pro tier API key.

Parameter	Type	Default	Description
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Understand whether coins are moving at profit or loss. SOPR > 1 means holders are selling at profit; SOPR < 1 means selling at a loss (often signals capitulation or bottom formation).

`get_cohort_metrics`

Pro

Get age cohort metrics: supply (BTC), realized cap (USD), and realized price (USD) for a specific UTXO age bracket. Used for HODL Waves analysis.

Parameter	Type	Default	Description
`cohort`	enum	required	Age bracket (see below)
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Valid cohorts: 24h, 1d_1w, 1w_1m, 1m_3m, 3m_6m, 6m_12m, 1y_2y, 2y_3y, 3y_5y, 5y_7y, 7y_10y, 10y_plus

Use case: Deep-dive into specific age groups. For example, check if the 3m_6m cohort is growing (new accumulation maturing) or if 10y_plus coins are finally moving (long-dormant supply waking up).

`get_utxo_history`

Pro

Get UTXO set breakdown by age cohort. Shows token amounts (BTC) and USD values for each cohort on a given date.

Parameter	Type	Default	Description
`date_processed`	string	—	Specific snapshot date (`YYYY-MM-DD`)
`cohort_start`	string	—	Start of cohort date range
`cohort_end`	string	—	End of cohort date range
`days`	integer	`1000`	Number of records (1–50,000)

Use case: Analyze coin dormancy and accumulation patterns. When dormant supply moves, it often precedes significant price action.

`get_latest_metrics`

Free

Get the most recent snapshot across all metric categories (price, supply, valuation, profit) in a single call.

Parameters: None

Use case: Quick market overview. One call gives you the current state of all key metrics — ideal for daily check-ins or starting a deeper analysis.

`search_metrics`

Free

Search available metrics by keyword across names, descriptions, and IDs.

Parameter	Type	Default	Description
`query`	string	required	Search term (e.g. `"realized price"`, `"MVRV"`, `"supply"`)

Use case: Find the right metric when you know roughly what you're looking for but not the exact ID. Returns matching metrics with their endpoints and tier requirements.

`get_metric`

Free

Get the full definition of a single metric by its ID, including name, description, category, endpoint, unit, and access tier.

Parameter	Type	Default	Description
`metric_id`	string	required	Metric identifier (e.g. `"lth_supply"`, `"price"`, `"sth_sopr"`)

Use case: Look up exactly what a metric measures, how it's calculated, and what tier is required before fetching the data. The response includes params and params_schema when the metric requires additional parameters (e.g., exchange, ticker, id).

`get_categories`

Free

List all metric categories with counts and the metric IDs in each category.

Parameters: None

Use case: Get a structured overview of available data organized by theme (price, supply, valuation, profit).

`get_coindays`

Free

Get Coin Days metrics: Coin Days Destroyed (CDD), liveliness, vaultedness, and dormancy. These metrics measure how long coins have been held before being spent, revealing conviction and activity patterns.

Parameter	Type	Default	Description
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Detect when long-dormant coins start moving. High CDD spikes often precede major price moves. Rising liveliness = old coins being spent; rising vaultedness = coins being locked away for long-term holding.

`get_etf_data`

Free

Get Bitcoin ETF aggregate data: total holdings (BTC), AUM (USD), daily net flows, cumulative flows, ETF dominance, and ETF realized price.

Parameter	Type	Default	Description
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Track institutional demand through ETF flows. Rising AUM and positive net flows signal institutional accumulation. Compare ETF realized price to spot price to gauge whether ETF holders are in profit.

`get_blockchain`

Free

Get blockchain metrics: block height or blocks mined per day.

Parameter	Type	Default	Description
`metric`	enum	required	`"block_height"` or `"blocks_mined"`
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Monitor network health and mining activity. Blocks mined per day deviating from ~144 can indicate hashrate changes or difficulty adjustments.

`get_dat_aggregate`

Free

Get Digital Asset Treasuries aggregate data: total BTC held by institutions and governments, company count, net flows, public/private/government breakdown.

Parameter	Type	Default	Description
`days`	integer	`30`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Track institutional Bitcoin adoption. Rising total BTC across corporate and sovereign treasuries signals growing institutional conviction.

For realized price (cost basis per BTC) by entity type (government, public, private), use render_chart with metrics dat_rp_total, dat_rp_public, dat_rp_government, dat_rp_private, or template dat-realized-price-by-type.

`get_dat_registry`

Free

List all tracked Digital Asset Treasury entities (corporations, funds, governments) with metadata including name, ticker, entity type, and country.

Parameters: None

Use case: Discover which entities hold Bitcoin. Use the returned id field to query per-entity data with get_dat_entity.

`get_dat_entity`

Pro

Get per-entity Digital Asset Treasury data: BTC holdings, AUM, net flow, cumulative flow, market share, realized price (average cost per BTC), and total cost basis.

Parameter	Type	Default	Description
`id`	integer	required	Entity/company ID (from `get_dat_registry`)
`days`	integer	`365`	Number of daily data points (1–10,000)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)

Use case: Analyze a specific entity's Bitcoin strategy — track holdings growth, compare realized price to market price for unrealized P/L, monitor accumulation patterns.

Example: get_dat_entity({ id: 1 }) returns Strategy (formerly MicroStrategy) data including 762K BTC holdings and $75,694 realized price.

`get_cycle_boundaries`

Free

Get Bitcoin halving cycle boundaries: start date, end date, duration in days, and cycle number for each halving epoch.

Parameters: None

Use case: Identify cycle phases for comparative analysis. Use with render_chart and x_axis: "day_offset" to overlay cycle performance charts where all cycles start at Day 0.

Example response (abbreviated):

[
  { "cycle": 1, "start_date": "2009-01-03", "end_date": "2012-11-28", "duration_days": 1426 },
  { "cycle": 2, "start_date": "2012-11-28", "end_date": "2016-07-09", "duration_days": 1319 },
  { "cycle": 3, "start_date": "2016-07-09", "end_date": "2020-05-11", "duration_days": 1402 },
  { "cycle": 4, "start_date": "2020-05-11", "end_date": "2024-04-20", "duration_days": 1441 },
  { "cycle": 5, "start_date": "2024-04-20", "end_date": null, "duration_days": null }
]

`render_chart`

Depends on metric

Render a Bitcoin on-chain analytics chart as a PNG image. Returns the image inline in the conversation. Supports single metrics, multiple metrics, templates, and full customization.

Parameter	Type	Default	Description
`metric`	string	—	Single metric ID (e.g., `"price"`, `"lth_supply"`)
`metrics`	array	—	Multiple metrics as strings or config objects
`template`	string	—	Chart template (e.g., `"mvrv_ratio"`, `"holder_supply"`)
`days`	integer	`365`	Days of history (7–3,650)
`start_date`	string	—	Start date (`YYYY-MM-DD`)
`end_date`	string	—	End date (`YYYY-MM-DD`)
`overlay`	`"price"`	—	Add BTC price overlay
`theme`	`"light"` / `"dark"`	`"light"`	Color theme
`width`	integer	`1200`	Image width in pixels
`height`	integer	`600`	Image height in pixels
`title`	string	auto	Chart title
`style`	`"line"` / `"area"` / `"bar"`	auto	Default chart style
`scale`	`"linear"` / `"log"`	`"linear"`	Y-axis scale
`y_axes`	array	—	Custom Y-axes with vertical zones. Each object: `{ id, side, scale?, format?, range?, domain_min?, domain_max?, no_padding? }`. See Snapshot API — Custom Y-Axes.
`format`	`"png"` / `"json"`	`"png"`	Output format

Use case: Visualize any metric directly in the conversation. The agent returns a chart image that appears inline — no need to open a browser or dashboard.

Example calls:

render_chart({ metric: "price" })
render_chart({ template: "mvrv_ratio", days: 730 })
render_chart({ metrics: ["lth_supply", "sth_supply"], style: "area", days: 730 })
render_chart({ metric: "funding_binance" })
render_chart({ metrics: [{ id: "funding_binance", params: { exchange: "binance" } }] })
render_chart({ metric: "cycle_performance", x_axis: "day_offset", scale: "log" })
render_chart({ heatmap_id: "cost-basis-distribution", heatmap_period: "1y", theme: "dark" })

Some metrics require parameters (like exchange or ticker). When using the metrics array with config objects, include params from the metric definition.

See Snapshot API for full documentation on chart rendering options.

Use Cases with Example Prompts

Here are concrete prompts you can give your AI agent once the Blocklens MCP server is connected.

Market Valuation Analysis

"Is Bitcoin currently overvalued? Check the MVRV ratio and compare LTH vs STH realized prices to the current spot price."

The agent will call get_holder_valuation and get_prices, then synthesize the data to assess whether current market value is above or below the aggregate cost basis.

HODL Waves Research

"Show me how the supply distribution across age cohorts has changed over the last year. Are long-term holders accumulating or distributing?"

The agent will call get_cohort_metrics for multiple cohorts with days: 365, then analyze trends in each age bracket to identify accumulation vs distribution patterns.

Weekly On-Chain Report

"Generate a weekly Bitcoin on-chain health report covering price action, supply dynamics, holder profitability, and MVRV."

The agent will call get_latest_metrics for a snapshot, then drill into get_prices, get_holder_supply, get_holder_valuation, and get_holder_profit for 7-day trends, producing a structured summary.

Cycle Phase Identification

"What does the realized cap trend suggest about the current market phase? Compare realized cap growth rate to previous months."

The agent will call get_holder_valuation with a longer time window and analyze the realized cap trajectory to identify whether we're in accumulation, markup, distribution, or markdown.

Capitulation Detection

"Check if STH SOPR has dropped below 1 in the last 30 days — this indicates short-term holders selling at a loss."

The agent will call get_holder_profit with days: 30 and examine the STH SOPR values to flag capitulation events.

Access Tiers

Tier	MCP Access	History	Metrics	Daily Requests
Demo (no key)	Yes	60 days	Basic (grade 0)	Unlimited
Pro ($50/mo)	Yes	Unlimited	All (grade 0–1)	10,000
Enterprise ($900/mo)	Yes	Unlimited	All (grade 0–2)	100,000

The MCP server works with all tiers. Demo mode is a great way to explore the tools before subscribing. Get an API key to unlock full access.

Get Your API Key

Visit blocklens.co/api-mcp to create an API key and view your subscription tier and usage.

Resources

Remote MCP endpoint: mcp.blocklens.co
npm package: blocklens-mcp-server
Source code: GitHub
llms.txt: docs.blocklens.co/llms.txt
AI plugin manifest: docs.blocklens.co/.well-known/ai-plugin.json
Snapshot API docs: Chart Snapshot API
API reference: Interactive API docs
Get API key: blocklens.co/api-mcp
MCP protocol: modelcontextprotocol.io

What is MCP?​

Remote Access (No Install Required)​

Claude.ai​

Claude Desktop​

ChatGPT​

Cursor / Windsurf​

Any MCP HTTP Client​

Authentication​

Free Access (No API Key)​

Full Access (With API Key)​

Why Blocklens + MCP?​

Local Install (Alternative)​

Install​

Claude Desktop​

Cursor / Windsurf​

Demo Mode (No API Key)​

Available Tools​

Tier Requirements​

list_metrics​

get_prices​

get_holder_supply​

get_holder_valuation​

get_holder_profit​

get_cohort_metrics​

get_utxo_history​

get_latest_metrics​

search_metrics​

get_metric​

get_categories​

get_coindays​

get_etf_data​

get_blockchain​

get_dat_aggregate​

get_dat_registry​

get_dat_entity​

get_cycle_boundaries​

render_chart​

Use Cases with Example Prompts​

Market Valuation Analysis​

HODL Waves Research​

Weekly On-Chain Report​

Cycle Phase Identification​

Capitulation Detection​

Access Tiers​

Get Your API Key​

Resources​

What is MCP?

Remote Access (No Install Required)

Claude.ai

Claude Desktop

ChatGPT

Cursor / Windsurf

Any MCP HTTP Client

Authentication

Free Access (No API Key)

Full Access (With API Key)

Why Blocklens + MCP?

Local Install (Alternative)

Install

Claude Desktop

Cursor / Windsurf

Demo Mode (No API Key)

Available Tools

Tier Requirements

`list_metrics`

`get_prices`

`get_holder_supply`

`get_holder_valuation`

`get_holder_profit`

`get_cohort_metrics`

`get_utxo_history`

`get_latest_metrics`

`search_metrics`

`get_metric`

`get_categories`

`get_coindays`

`get_etf_data`

`get_blockchain`

`get_dat_aggregate`

`get_dat_registry`

`get_dat_entity`

`get_cycle_boundaries`

`render_chart`

Use Cases with Example Prompts

Market Valuation Analysis

HODL Waves Research

Weekly On-Chain Report

Cycle Phase Identification

Capitulation Detection

Access Tiers

Get Your API Key

Resources