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.
What it does
- 13 MCP tools covering counter management, goals, the Reporting API and the full Logs API lifecycle.
- Reporting API queries with built-in period comparison: pass date1_b/date2_b to get metrics for segments A and B.
- Logs API raw export: evaluate, create, poll, download parts and clean, with a 50KB preview by default.
- Eight tools only read; five change the account, and each tool declares readOnlyHint and destructiveHint.
- Runs locally over stdio from a Docker image on GHCR — no web server, no persistent storage, no daemons.
- Token via environment variable only, never logged; the image runs as a non-root user.
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
| Tool | Description |
|---|---|
yandex_metrica_list_counters | List accessible counters (tags) |
yandex_metrica_get_counter | Get counter details by ID |
yandex_metrica_list_goals | List goals for a counter |
yandex_metrica_create_counter | Create a new counter (add a site) |
yandex_metrica_delete_counter | Delete a counter permanently |
Reporting API (aggregated)
| Tool | Description |
|---|---|
yandex_metrica_get_report | Run a Reporting API query |
For period comparison, pass
date1_b/date2_btoyandex_metrica_get_report. The tool automatically routes to/stat/v1/data/comparison;date1/date2become segment A,date1_b/date2_bbecome segment B. Each result row returnsmetrics: { a, b }.
Logs API (raw export)
| Tool | Description |
|---|---|
yandex_metrica_evaluate_logs_request | Check if export is possible |
yandex_metrica_create_logs_request | Create an async export request |
yandex_metrica_list_logs_requests | List all requests for a counter |
yandex_metrica_get_logs_request | Poll status of a request |
yandex_metrica_download_logs_part | Download a processed part (TSV) |
yandex_metrica_cancel_logs_request | Cancel a pending request |
yandex_metrica_clean_logs_request | Clean processed files to free quota |
Example prompts
- Why did my site lose visits last week?
- Which traffic sources sent the most visits last month?
- What goals are configured on my main counter?
- Compare this month's visits with the same month last year.
- Export raw visits for the first week of January and show a preview.
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
- yandex-metrica-mcpMCP server for the Yandex Metrica Reporting API, Logs API and counter management, designed for use with Claude Code and Codex CLI. Eight of its 13 tools…