yandex-metrika-mcp

MCP server for Yandex Metrika API. Access web analytics data -- traffic summaries, audience demographics, traffic sources, popular pages, search phrases, and custom reports.

Installation

This package is published as @stufently/yandex-metrika-mcp; the unscoped name yandex-metrika-mcp belongs to an unrelated publisher (see the note in the root README). Nothing is on the scope yet, so run it from source:

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-metrika-mcp/src/index.mjs

Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-metrika-mcp/src/index.mjs"],
      "env": {
        "YANDEX_METRIKA_TOKEN": "your-oauth-token"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
YANDEX_METRIKA_TOKEN	Yes	OAuth token. metrika:read covers the 10 read tools; metrika:write is also required by create-counter and delete-counter
YANDEX_METRIKA_SCOPE	No	Override the scopes the auth flow requests. Default: metrika:read metrika:write
YANDEX_CLIENT_ID	For auth flow	Yandex OAuth app client ID
YANDEX_CLIENT_SECRET	For auth flow	Yandex OAuth app client secret

Authentication

To obtain an OAuth token interactively:

node packages/yandex-metrika-mcp/src/index.mjs auth

This opens a browser for Yandex OAuth authorization and returns a token. Set it as YANDEX_METRIKA_TOKEN.

Scopes

The helper requests metrika:read metrika:write by default. The write scope is not optional decoration: create-counter and delete-counter are rejected with HTTP 403 without it, and the rejection arrives at the moment you try to create a counter, not at setup time.

For a token that can only read, ask for less:

YANDEX_METRIKA_SCOPE="metrika:read" node packages/yandex-metrika-mcp/src/index.mjs auth

The two write tools then fail with a 403 whose message names the missing scope. Both tools also say so in their own descriptions, so a model can tell the difference between "not allowed" and "broken" before calling them.

A write-capable token no longer means an unguarded delete: delete-counter requires an explicit confirm: true regardless of scope — see Deleting a counter.

Note: The Metrika API uses Authorization: OAuth {token} (not Bearer).

Tool Reference (12 tools)

Management (5)

Tool	Description	Parameters
get-counters	List all Metrika counters (sites)	--
get-counter	Get details for a specific counter	counter_id
get-goals	Get goals for a counter	counter_id
create-counter	Create a new counter (add a site). Needs metrika:write	name, site, mirrors?, time_zone_name?, gdpr_agreement_accepted?
delete-counter	Delete a counter. Irreversible — see Deleting a counter. Needs confirm: true and metrika:write	counter_id, confirm

Deleting a counter

delete-counter is the only irreversible tool here, and it refuses to run unless the call carries confirm: true:

{ "counter_id": 12345, "confirm": true }

Called without it, the tool returns an error result and sends nothing to the Metrika API:

Refused: `delete-counter` requires explicit confirmation.

Deleting counter 12345 is irreversible — the counter and every statistic it has collected are
gone for good. Yandex cannot restore them, and creating a new counter for the same site does
not bring the history back.

Nothing was sent to the Metrika API — no counter was touched.

To go ahead, call `delete-counter` again with counter_id 12345 and `confirm: true`. To check
which site this counter belongs to first, call `get-counter`.

confirm is optional in the JSON schema on purpose: a missing confirmation has to come back as that explanation, not as a schema validation error a model cannot act on. Only a literal true counts — "true", 1 and "yes" are refused, because a guess at the protocol is not a decision to delete anything. The tool is also marked destructiveHint: true in its MCP annotations, so clients that surface tool risk can show it before the call.

Why the parameter exists: until the default OAuth scope included metrika:write, an accidental delete-counter was stopped by the 403 a read-only token produced. Fixing that 403 (so setup works the first time) removed the only real brake, and "Irreversible" in a description is a hope that the model reads carefully, not a guard.

Reporting (6)

Tool	Description	Parameters
get-traffic-summary	Visits, users, pageviews, bounce rate, avg duration	counter_id, date_from?, date_to?
get-traffic-sources	Traffic breakdown by source	counter_id, date_from?, date_to?, limit? (default: 10)
get-geography	Traffic breakdown by country and city	counter_id, date_from?, date_to?, limit? (default: 10)
get-devices	Traffic breakdown by device, browser, or OS	counter_id, group_by? (device/browser/os, default: device), date_from?, date_to?, limit? (default: 10)
get-popular-pages	Most visited pages	counter_id, date_from?, date_to?, limit? (default: 10)
get-search-phrases	Top search phrases driving traffic	counter_id, date_from?, date_to?, limit? (default: 20)

Custom (1)

Tool	Description	Parameters
get-report	Run a custom report with arbitrary metrics and dimensions	counter_id, metrics, dimensions?, date_from?, date_to?, filters?, sort?, limit? (default: 10)

get-report Parameters

The get-report tool provides full access to the Metrika Stat API:

Parameter	Type	Required	Description
counter_id	number	Yes	Counter ID
metrics	string	Yes	Comma-separated metrics (e.g., ym:s:visits,ym:s:users)
dimensions	string	No	Comma-separated dimensions (e.g., ym:s:trafficSource)
date_from	string	No	Start date YYYY-MM-DD (default: 30 days ago)
date_to	string	No	End date YYYY-MM-DD (default: today)
filters	string	No	Filter expression (e.g., ym:s:trafficSource=='organic')
sort	string	No	Sort field, prefix with - for descending
limit	number	No	Max results (default: 10)

Default Date Range

When date_from and date_to are not specified, all reporting tools default to the last 30 days.

Data Sampling

The Metrika Stat API may return sampled data for large datasets. When sampling is applied, the response includes a note indicating that figures are approximate.

License

MIT