Yandex Metrika MCP with DuckDB
Yandex.Metrika MCP
A Metrika MCP server for Claude Code with Stat, Logs, Management and Compare APIs plus local SQL analysis of raw logs via DuckDB
Low risk
We rate an entry low when it mostly gives the agent instructions and reference material.
Why this level
- All tools only read reports and logs; there is no write access to Metrika
- Downloaded raw visit logs are stored locally and need careful privacy handling
Install
Manual install
git clone https://github.com/belisgard/yandex-metrika-mcp.git && cd yandex-metrika-mcp && uv sync && cp .env.example .envAfter filling .env with the token and counter ID, open the folder in Claude Code; it connects via the project-scoped .mcp.json.
This is third-party code. Review the repository files before installing.
What it does
A local Python server provides 15 tools: counter summary, goals and segments, aggregated Stat API reports, a searchable metrics and dimensions dictionary, the full Logs API cycle (request export, poll status, download) with automatic caching to parquet and DuckDB view registration, plus period and segment comparison. The run_sql tool lets the agent build cohorts and funnels with SQL directly over the downloaded logs, but only allows SELECT, WITH, SHOW and DESCRIBE, and DuckDB file functions are blocked. The only outbound traffic is to api-metrika.yandex.net, everything else runs locally.
Who it is for. For analysts who build funnels and cohorts from raw Metrika visit logs right inside a Claude Code chat.
Good fit when
- You need ad-hoc SQL analysis of raw visits, not just canned reports
- You need both aggregated Stat API reports and period or segment comparison
- It matters that the token and raw visit data never leave your local machine
Not a fit when
- You need Direct or Webmaster access: the server only covers Metrika
- You need to manage counters, goals or segments, not just read them
Example request
Of users who saw the product page, what percent added to cart and then checked outLimitations
The package is not published to PyPI; install by cloning and uv sync. No writes to Metrika: the server only reads reports and logs, goals and counters cannot be managed. Downloaded logs and the DuckDB file live locally under data/ and are gitignored, but they contain raw visit data that should be handled per your privacy policy.
How to disable. Remove the yandex-metrika server from .mcp.json or your global Claude Code config.
MCP
- Transport
- stdio
- Authentication
- API key
| Environment variables | |
|---|---|
| YM_OAUTH_TOKEN required, secret | Yandex OAuth token with metrika:read scope |
| YM_COUNTER_ID required | Metrika counter ID |
| YM_TIMEZONE | Report timezone, has a default |
| YM_DATA_DIR | Folder for the parquet cache and the DuckDB file |
Security check
- All tools only read reports and logs; there is no write access to Metrika
- Downloaded raw visit logs are stored locally and need careful privacy handling
README in short
The README walks through getting an OAuth token and ClientID at oauth.yandex.ru, finding the counter ID, installing via uv and a Management API smoke test. It lists all 15 tools in a table, a five-step typical Logs API workflow, a troubleshooting section for 403 and 429 errors, and a security section about the run_sql sandbox.
FAQ
Can it build funnels from raw data?
Yes, request_logs and download_logs export the Logs API to parquet, and run_sql runs read-only SQL over it via DuckDB.
What token scope is needed?
metrika:read is enough; the author explicitly notes it is the only required permission.
Related
Official DataLens (Yandex) skills for Claude Code, Codex and OpenCode: SDK, HTML reports and RLS resolution
A Yandex Metrika MCP server generated from the API spec: 108 methods, 10 tools declared by default, transparent filters and response metadata
An open MCP server and agent skill set for SEO: keyword research, competitors, backlinks and site audits powered by DataForSEO
A Claude Code plugin for SEO audits: technical SEO, E-E-A-T, schema, local and AI search via parallel subagents