Yandex Metrica MCP

Open source · MIT · Docker · Node.js 24+

MCP server for the Yandex Metrica Reporting API, Logs API and counters

13 MCP tools over stdio for Claude Code, Codex and Cursor: Metrica reports, raw Logs API export, counters and goals. Run with Docker, MIT.

Get started Read the docsView on GitHub

What it does

Installation

docker run -i --rm -e YANDEX_METRICA_TOKEN ghcr.io/stufently/yandex-metrica-mcp:latest

One path that works today: Docker. Nothing to clone, no Node.js. Every MCP client below starts the server with this same command.

-e YANDEX_METRICA_TOKEN without a value forwards the variable from the client's environment into the container, so the token lives in the client's env block and never appears in the docker command line or ps output. The client pulls the image on first start; docker pull ghcr.io/stufently/yandex-metrica-mcp:latest up front just makes that first start faster.

Smoke test without a token or network — the server must answer initialize and list 13 tools. The image ships a placeholder YANDEX_METRICA_TOKEN so it starts for introspection; tool calls with it return a "YANDEX_METRICA_TOKEN is not set" error instead of reaching Yandex:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | docker run -i --rm --network none ghcr.io/stufently/yandex-metrica-mcp:latest

Image tags on GHCR: latest and main (every push to main), sha-<short>, and X.Y.Z / X.Y / X on version tags. Pin a version tag (:0.2.3) for reproducible setups.

npm (not published yet)

The package is scoped — both unscoped names (yandex-metrica-mcp and the project's former name mcp-yandex-metrica) belong to unrelated projects on npm — so it ships as @stufently/yandex-metrica-mcp (command yandex-metrica-mcp). The first npm release has not been cut, so npx -y @stufently/yandex-metrica-mcp does not work today. Use Docker.

From source

git clone https://github.com/stufently/yandex-metrica-mcp.git
cd yandex-metrica-mcp
npm install && npm run build

See Running from a local build for the client config.


Supported MCP Tools

Counter Management

ToolDescription
yandex_metrica_list_countersList accessible counters (tags)
yandex_metrica_get_counterGet counter details by ID
yandex_metrica_list_goalsList goals for a counter
yandex_metrica_create_counterCreate a new counter (add a site)
yandex_metrica_delete_counterDelete a counter permanently

Reporting API (aggregated)

ToolDescription
yandex_metrica_get_reportRun a Reporting API query

For period comparison, pass date1_b/date2_b to yandex_metrica_get_report. The tool automatically routes to /stat/v1/data/comparison; date1/date2 become segment A, date1_b/date2_b become segment B. Each result row returns metrics: { a, b }.

Logs API (raw export)

ToolDescription
yandex_metrica_evaluate_logs_requestCheck if export is possible
yandex_metrica_create_logs_requestCreate an async export request
yandex_metrica_list_logs_requestsList all requests for a counter
yandex_metrica_get_logs_requestPoll status of a request
yandex_metrica_download_logs_partDownload a processed part (TSV)
yandex_metrica_cancel_logs_requestCancel a pending request
yandex_metrica_clean_logs_requestClean processed files to free quota

Example prompts

FAQ

How do I install the Yandex Metrica MCP server?

Use Docker: docker run -i --rm -e YANDEX_METRICA_TOKEN ghcr.io/stufently/yandex-metrica-mcp:latest. Nothing to clone and no Node.js needed. The npm package @stufently/yandex-metrica-mcp is not published yet.

Which token do I need?

A Yandex OAuth token with the metrika:read scope in YANDEX_METRICA_TOKEN. Creating and deleting counters requires the metrika:write scope.

Which AI clients does it work with?

Any MCP client over stdio. The README has configs for Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI and Zed; Claude Code on Ubuntu is verified in daily use, the others are documented only.

Is the server read-only?

No. Eight of the 13 tools only read. Five change your Metrica account: create and delete a counter, and create, cancel and clean a Logs API export.

How does the Logs API export work?

It is asynchronous: evaluate, create a request, poll yandex_metrica_get_logs_request until status is processed, download each part, then clean. Parts return a 50KB preview unless you set mode to full.

Does it cache responses?

No. Every tool call hits the Yandex API. Retries with exponential backoff are built in: 3 retries on statuses 429, 500, 502, 503 and 504.

Documentation pages