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
- 0 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Downloads raw visit logs with visitor identifiers via the Logs API and stores them locally
- The agent runs DuckDB SQL queries over those logs
- Writes nothing to Metrica, needs an OAuth token
Install
- Works in
- Services
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.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Downloads raw visit logs with visitor identifiers via the Logs API and stores them locally
- The agent runs DuckDB SQL queries over those logs
- Writes nothing to Metrica, needs an OAuth token
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 outMCP
- Transport
- stdio
- Authentication
- API key
Environment variables
YM_OAUTH_TOKENrequired, secret- Yandex OAuth token with metrika:read scope
YM_COUNTER_IDrequired- Metrika counter ID
YM_TIMEZONE- Report timezone, has a default
YM_DATA_DIR- Folder for the parquet cache and the DuckDB file
Limitations
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.
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.
Discussion
No questions or reviews yet.
Related
All Yandex Metrica toolsYandex Metrika MCP with device flow and Logs API
yandex-metrika-mcp
A Yandex Metrika MCP server for Claude Desktop with a browserless OAuth device flow and the full Logs API cycle
A read-only MCP server for Yandex Metrika: reports with exact dates, time zone and sampling status, browser sign-in.
Yandex Metrica MCP: reports and goals in Claude, Cursor and Codex
mcp-yandex-metrica
A Metrica MCP server run with npx and Yandex OAuth sign-in inside the chat: counters, goals, visit and conversion reports, read-only by default
A Yandex Metrika MCP server generated from the API spec: 108 methods, 10 tools declared by default, transparent filters and response metadata
An MCP server, CLI and Pydantic models for the Yandex Metrika API: reports, counters, goals, filters, segments, logs and offline conversion uploads
MCP Yandex Metrica with counter management
@theyahia/yandex-metrika-mcp
Yandex Metrica MCP server with 15 tools: reports and traffic plus creating, editing, and deleting counters and goals
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Yandex Metrika MCP with DuckDB (this card) | no | API key | 0 | |
| Yandex Metrika MCP Server (Node.js) | no | API key | 1 | fixed report bugs |
| MCP Yandex Metrica with counter management | no | API key | 1 | manage counters and goals |
| Yandex Metrika MCP Server (ymetrika-mcp) | no | API key | 0 | on FastMCP, with OpenTelemetry tracing |
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.