# io.github.blocklens/blocklens-mcp-server (npm · blocklens-mcp-server)

Bitcoin on-chain analytics — 109 metrics: MVRV, SOPR, NUPL, HODL Waves, CDD, cycles & more

- Trust score: 66/100 (medium)
- Change this week: +15
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `blocklens-mcp-server`: 66/100 (this document), [markdown](https://verifymcp.io/servers/blocklens-blocklens-mcp-server/blocklens-mcp-server.md), [page](https://verifymcp.io/servers/blocklens-blocklens-mcp-server/blocklens-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `blocklens-mcp-server`
- Version: `0.4.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 86/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 77 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 79/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2537 tokens (~158/item across 16 items; 15 tools + 1 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add blocklens-blocklens-mcp-server -- npx -y blocklens-mcp-server
```

### Codex

```bash
codex mcp add blocklens-blocklens-mcp-server -- npx -y blocklens-mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blocklens-blocklens-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "blocklens-mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add blocklens-blocklens-mcp-server --command npx --arg -y --arg blocklens-mcp-server
```

### Hermes

```yaml
mcp_servers:
  blocklens-blocklens-mcp-server:
    command: "npx"
    args: ["-y", "blocklens-mcp-server"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 66, +36)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Capabilities: pass → unverified
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional] Licence: MIT

### 2026-08-01 (score 30, +5)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] MCP protocol: unverified → pass

### 2026-07-31 (score 25, −26)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 51)

First indexed and scored.

## MCP tools (15)

### `list_metrics` (~43 tokens)

List all available on-chain metrics with descriptions, categories, and tier requirements. Returns id, name, description, category, unit, endpoint, and access tier for each metric.

### `get_prices` (~107 tokens)

Get daily OHLC prices (open/high/low/close in USD), market cap, and 24h trading volume. Returns one row per day, newest first.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.
- `symbol` (string): Cryptocurrency symbol (default: BTC)

### `get_holder_supply` (~109 tokens)

Get Bitcoin holder supply breakdown: Long-Term Holder (LTH) supply, Short-Term Holder (STH) supply, and circulating supply. LTH = held >155 days, STH = held <155 days. Values in BTC.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.

### `get_holder_valuation` (~127 tokens)

Get Bitcoin valuation metrics: Realized Cap (USD), Realized Price (USD), LTH/STH Realized Cap and Price, MVRV ratio (Market Value / Realized Value), and Unrealized P/L. MVRV > 3.5 historically signals overheating; < 1 signals undervaluation.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.

### `get_holder_profit` (~110 tokens)

Get Bitcoin profit metrics: LTH/STH Realized P/L (USD) and SOPR (Spent Output Profit Ratio). SOPR > 1 means coins moved at profit; < 1 means at loss. Requires Pro tier API key.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.

### `get_cohort_metrics` (~207 tokens)

Get age cohort metrics: supply (BTC), realized cap (USD), and realized price (USD) for a specific UTXO age bracket. 12 cohorts from <24h to 10y+. Used for HODL Waves analysis to track accumulation/distribution by coin age.

Input parameters:

- `cohort` (string, required): Age cohort: 24h, 1d_1w, 1w_1m, 1m_3m, 3m_6m, 6m_12m, 1y_2y, 2y_3y, 3y_5y, 5y_7y, 7y_10y, 10y_plus
- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.

### `get_utxo_history` (~127 tokens)

Get UTXO set breakdown by age cohort. Shows token amounts (BTC) and USD values for each cohort date. Useful for analyzing coin dormancy and accumulation patterns — when dormant supply moves, it often precedes price action.

Input parameters:

- `cohort_end` (string): End of cohort date range (YYYY-MM-DD)
- `cohort_start` (string): Start of cohort date range (YYYY-MM-DD)
- `date_processed` (string): Specific processing date (YYYY-MM-DD). Returns the UTXO snapshot for that day.
- `days` (integer): Number of records to return

### `get_latest_metrics` (~43 tokens)

Get the most recent snapshot across all metric categories (price, supply, valuation, profit) in a single call. Ideal for a quick market overview without specifying date ranges.

### `search_metrics` (~70 tokens)

Search available metrics by name or description. Returns matching metrics with their IDs, API endpoints, access tiers, and descriptions. Use this to discover which metrics are available before fetching data.

Input parameters:

- `query` (string, required): Search query (e.g. "realized price", "supply", "MVRV")

### `get_metric` (~78 tokens)

Get the full definition of a single metric by its ID. Returns name, description, category, endpoint, unit, access tier, documentation, and related metrics. Use search_metrics or list_metrics first to find metric IDs.

Input parameters:

- `metric_id` (string, required): Metric identifier (e.g. "lth_supply", "price", "sth_sopr")

### `get_categories` (~39 tokens)

List all metric categories with counts and metric IDs in each. Categories include: price, supply, valuation, profit. Useful for discovering what data is available.

### `get_coindays` (~118 tokens)

Get Coin Days metrics: CDD, binary CDD, supply-adjusted CDD, liveliness, vaultedness, dormancy, dormancy flow, transferred price, and transfer volume. Coin Days measure the economic weight of Bitcoin transactions by accounting for both amount and holding time.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.

### `get_blockchain` (~92 tokens)

Get blockchain network metrics: block height or daily blocks mined.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `metric` (string, required): Blockchain metric: "block_height" or "blocks_mined"
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.

### `get_cycle_performance` (~129 tokens)

Get Bitcoin cycle performance data. Shows price progression indexed from cycle reference points (lows, ATHs, halvings). Without type parameter returns aggregate cycle comparison; with type returns individual cycle tracks.

Input parameters:

- `days` (integer): Number of daily data points to return
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days param when set.
- `type` (string): Cycle reference point type: "low", "ath", or "halving". Omit for aggregate comparison.

### `render_chart` (~1123 tokens)

Render a Bitcoin on-chain analytics chart as a PNG image. Supports single metrics, multiple metrics, templates, computed formulas, and full customization.

Use this when the user asks to "show", "chart", "plot", "graph", or "visualize" any metric.

Smart defaults: just provide metric IDs and you get a beautiful chart. Customize with optional params.

Supports custom Y-axes with vertical zones (stack volume below price), domain clamping, reference lines, reference areas, and computed formula series.

IMPORTANT — Multi-axis guidance for different units:
When combining metrics with different units (e.g., BTC supply + USD price, or a dimensionless ratio + USD), ALWAYS place them on separate Y-axes. Otherwise one metric will appear as a flat line near zero due to scale mismatch. Use list_metrics to check the "unit" field and assign metrics with different units to different axes (left vs right).

Examples:
\- Simple: render_chart({ metric: "price" })
\- Multi-metric: render_chart({ metrics: ["lth_supply", "sth_supply"], days: 730, style: "area" })
\- Template: render_chart({ template: "mvrv_ratio" })
\- Custom: render_chart({ metrics: [{ id: "price", axis: "right" }, { id: "lth_mvrv", axis: "left" }], days: 365, title: "Price vs MVRV" })
\- Multi-unit (separate axes): render_chart({ metrics: [{ id: "lth_supply", axis: "left" }, { id: "price", axis: "right" }], days: 365 })
\- Vertical zones: render_chart({ metrics: [{ id: "price", y_axis_id: "ax-p" }, { id: "volume", y_axis_id: "ax-v", style: "bar" }], y_axes: [{ id: "ax-p", side: "right", range: [20, 100] }, { id: "ax-v", side: "left", range: [0, 20] }] })
\- Reference line: render_chart({ metric: "lth_mvrv", reference_lines: [{ y: 3.5, label: "Overheated", stroke: "#ef4444", dash: "3 3" }] })
\- Reference area: render_chart({ metric: "lth_mvrv", reference_areas: [{ y1: 0, y2: 0.85, label: "Undervalued", fill: "#22c55e", fill_opacity: 0.15 }] })
\- Formula (ratio): render_chart({ metrics: [{ id: "lth_supply" }, { id: "sth_supply…

Input parameters:

- `days` (integer): Days of history (default: 365)
- `end_date` (string): End date (YYYY-MM-DD). Defaults to today.
- `format` (string): Output format: png (image) or json (metadata)
- `formulas` (array): Computed series derived from metric data. Formulas reference metrics by position (m1, m2, ...) and support arithmetic (+, -, *, /). Use together with metrics to add derived indicators.
- `height` (integer): Image height in pixels
- `metric` (string): Single metric ID (e.g., "price", "lth_supply", "lth_mvrv"). Use list_metrics to discover IDs.
- `metrics`: Multiple metrics. Pass as string array ["price", "lth_supply"] for simple, or objects for customization.
- `overlay` (string): Add BTC price overlay (subtle dashed line)
- `reference_areas` (array): Shaded reference zones between two Y values. Example: highlight when MVRV < 0.85
- `reference_lines` (array): Horizontal reference lines on the chart
- `scale` (string): Y-axis scale
- `start_date` (string): Start date (YYYY-MM-DD). Overrides days.
- `style` (string): Default chart style for all metrics
- `template` (string): Chart template ID. Templates: price, price_volume, market_cap, holder_supply, mvrv_ratio, realized_price, realized_cap, unrealized_pl, realized_pl, sopr, block_height, realized_volatility, coindays_d…
- `theme` (string): Color theme: light or dark
- `title` (string): Chart title (auto-generated if omitted)
- `width` (integer): Image width in pixels
- `y_axes` (array): Custom Y-axes with vertical zones. Use range to stack axes (e.g. volume [0,20], price [20,100]). Use domain_min/domain_max to clamp axis bounds.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/blocklens-blocklens-mcp-server/blocklens-mcp-server#diagnostics

## Score history

- 2026-08-03: 66
- 2026-08-02: 66
- 2026-08-01: 30
- 2026-07-31: 25
- 2026-07-30: 51
- 2026-07-28: 51
- 2026-07-27: 51

## Links

- npm package: https://www.npmjs.com/package/blocklens-mcp-server
- Socket report: https://socket.dev/npm/package/blocklens-mcp-server
- Repository: https://github.com/blocklens/blocklens-mcp-server
- Website: https://blocklens.co/
- Changelog RSS feed: https://verifymcp.io/servers/blocklens-blocklens-mcp-server/blocklens-mcp-server/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/blocklens-blocklens-mcp-server/blocklens-mcp-server/changelog.json
- HTML version of this page: https://verifymcp.io/servers/blocklens-blocklens-mcp-server/blocklens-mcp-server