{
  "markdown": "# yandex-metrica-mcp\n\n[![CI](https://github.com/BoxLab-Ltd/yandex-metrica-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/BoxLab-Ltd/yandex-metrica-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/yandex-metrica-mcp.svg)](https://www.npmjs.com/package/yandex-metrica-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n\n**Ask your Yandex Metrica analytics in plain language — from Claude, Cursor, or\nany MCP client.**\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for\n**Yandex Metrica**. It lets an AI agent query your web-analytics data — traffic,\nsources, landing pages, conversions, geography, devices and trends — through a\nsmall set of flexible, read-only tools.\n\n> Read-only by design, no secrets stored in the package: interactive login uses\n> a built-in public OAuth client with PKCE, and the server talks only to Yandex.\n\n> Status: early development (v0.1, work in progress). General-purpose: SEO is\n> one of many use cases, not the focus.\n\n## Demo\n\nPoint an AI agent at your counter and ask about your traffic — the server queries\nYandex Metrica and hands back real, read-only data, no dashboards. Here the\n`run_report` tool answers a “traffic sources, last 7 days” question against a live\ncounter:\n\n![yandex-metrica-mcp querying live Yandex Metrica traffic sources, read-only](docs/demo.gif)\n\n## Quickstart\n\n**1. Add the server to your MCP client** (e.g. Claude Desktop) — no token\nrequired up front; you log in interactively in step 2:\n\n```json\n{\n    \"mcpServers\": {\n        \"yandex-metrica\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"yandex-metrica-mcp\"],\n            \"env\": { \"YANDEX_METRIKA_COUNTER_ID\": \"12345678\" }\n        }\n    }\n}\n```\n\n**2. Log in once — one command, no app registration, no secret stored:**\n\n```bash\nnpx yandex-metrica-mcp auth\n```\n\nApprove access in the browser and you're done — the code is handed back\nautomatically over a local redirect, no copy-paste. The login uses\nauthorization-code + PKCE, so **no client secret ever touches your machine**; the\ntoken is cached (mode 0600) and valid for ~1 year.\n\n**3. Ask your agent** about traffic, sources, conversions, geography, devices, or\ntrends — see [Examples](#examples) for prompts.\n\nPrefer a static token (CI / non-interactive) or your own OAuth app? See\n[Authentication](#authentication).\n\n### Or install as a Claude Code plugin\n\nThe repo doubles as a plugin marketplace, so you can install the server through\nClaude Code's plugin system instead of the config above:\n\n```bash\n/plugin marketplace add BoxLab-Ltd/yandex-metrica-mcp\n/plugin install yandex-metrica-mcp@boxlab\n```\n\nThen run `npx yandex-metrica-mcp auth` once to log in.\n\n### Or install as a Claude Desktop extension (.mcpb)\n\nFor a one-click install with no JSON, download the `.mcpb` from the\n[latest release](https://github.com/BoxLab-Ltd/yandex-metrica-mcp/releases/latest)\nand open it with Claude Desktop (or drag it into Settings → Extensions). It asks\nfor an optional default counter id; then sign in from the chat with the `login`\ntool (or run `npx yandex-metrica-mcp auth`).\n\n## Why\n\nThere is no official Yandex Metrica MCP server, and existing community ones are\nmostly thin, unmaintained, or dump raw data straight into the model's context.\nThis server aims to be the well-engineered, well-maintained, open option:\nflexible report tools, strict token/context discipline, read-only by default.\n\n## Features (v0.1)\n\n- `run_report` — flexible wrapper over the Reporting API (`/stat/v1/data`).\n- `run_comparison` — compare two periods with absolute and percentage deltas.\n- `run_drilldown` — drill down through a dimension tree.\n- `run_timeseries` — metrics split into a time series (`/bytime`) for trends.\n- `get_metadata` — discover the counters on your account and a catalog of common\n  dimensions/metrics (and Logs API fields) so the model queries with real names.\n- `describe_counter` — read one counter's configuration (goals, segments,\n  filters, operations, access grants) via an `include` selector. The goals\n  section gives the goal ids needed for conversion metrics in `run_report`.\n- `logs_request` / `logs_status` / `logs_download` / `logs_clean` — Logs API:\n  export raw, un-sampled session (`visits`) or hit (`hits`) rows. Async lifecycle\n  (request → poll → download → clean); `logs_download` returns a bounded sample\n  inline by default, or streams the full export to a file — never dumping raw\n  rows into the model's context.\n- `login` / `submit_code` — sign in to Yandex Metrica from your MCP client, no\n  terminal needed: `login` opens the browser and captures the code over a local\n  redirect, or hands back a URL and takes the pasted code via `submit_code`.\n- Built-in context control: field selection on by default, low default row\n  limits, and sampling/quota surfaced back to the model.\n\nPlanned for later: Streamable HTTP transport, write tools (behind an explicit\nflag).\n\n## Requirements\n\n- Node.js >= 18\n- Yandex Metrica credentials with the `metrika:read` scope (see\n  **Authentication**). Whoever the credentials belong to must have access to the\n  counters you query.\n\n## Authentication\n\n**Recommended: interactive login.** No app registration needed — the server\nships a built-in public OAuth client. Run once:\n\n```bash\nyandex-metrica-mcp auth     # or, in dev: bun run auth\n```\n\nIt opens the Yandex consent page in your browser; after you approve, the code is\nreturned automatically over a loopback redirect (`http://127.0.0.1:53682`) — no\ncopy-paste. If that port is taken, it falls back to showing a code you paste in\n(force that flow with `auth --oob`, or change the port with\n`YANDEX_OAUTH_LOOPBACK_PORT`). The token is cached at\n`~/.config/yandex-metrica-mcp/token.json` (mode 0600) and is valid for ~1 year;\nre-run `auth` when it expires. The login uses authorization-code + PKCE, so **no\nclient secret is stored anywhere**. A cached login takes precedence over\n`YANDEX_METRIKA_TOKEN`.\n\n**From your MCP client (no terminal).** Not signed in yet? The server still\nstarts — ask your agent to run the `login` tool and it does the same browser\nflow in-process (or returns a URL and takes the code via `submit_code`). Handy\nfor GUI clients like Claude Desktop, where there is no terminal to run `auth`. Get a token for an app with the `metrika:read`\nscope at <https://oauth.yandex.ru> and pass it as `YANDEX_METRIKA_TOKEN` — handy\nfor CI or non-interactive use.\n\n**Own OAuth app (optional).** To use your own app instead of the built-in one,\nset `YANDEX_OAUTH_CLIENT_ID`; add `YANDEX_OAUTH_CLIENT_SECRET` to also enable\nautomatic token refresh.\n\n## Configuration\n\nThe [Quickstart](#quickstart) covers the happy path. For all options — static\ntoken, your own OAuth app, default counter, request tuning, language — see\n[`.env.example`](./.env.example). The published package runs on Node (so\n`npx`/MCP clients work out of the box); local development uses\n[Bun](https://bun.sh).\n\n## Examples\n\nOnce connected, an agent can answer questions like:\n\n- “How many visits and users did counter 12345678 get last week, split by traffic\n  source?” → `run_report` with `metrics: [\"ym:s:visits\",\"ym:s:users\"]`,\n  `dimensions: [\"ym:s:lastsignTrafficSource\"]`.\n- “Compare this week's organic conversions to last week's.” → `run_comparison`\n  (server returns A, B, and the deltas).\n- “Which operating systems do my visitors use? Let me drill into Windows\n  versions.” → `run_drilldown`, then again with `parentId`.\n- “What counters do I have?” → `get_metadata`.\n- “List this counter's goals, then show how the ‘Purchase’ goal converted last\n  week.” → `describe_counter` (`include: [\"goals\"]`) for the goal id, then\n  `run_report` with `ym:s:goal<id>conversionRate`.\n- “Export last month's raw sessions with landing pages and referrers for offline\n  analysis.” → `logs_request` (`source: \"visits\"`), poll `logs_status`, then\n  `logs_download` (`mode: \"file\"`), then `logs_clean` to free the quota.\n\n## Development\n\nThis project is Bun-first:\n\n```bash\nbun install\nbun run dev        # run from source with hot reload\nbun run typecheck  # tsc --noEmit\nbun run lint       # eslint\nbun test           # bun's test runner\nbun run build      # emit dist/ with tsc (Node-compatible)\n```\n\n## License\n\n[MIT](./LICENSE) © boxlab\n",
  "bytes": 8305,
  "sha": "b86ac60562eb961d90ed78c20876f98fc91fad51c2be38a3ebdba36e057b7e73",
  "repo_slug": "boxlab-ltd/yandex-metrica-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_boxlab_ltd_yandex_metrica_mcp_16aeaada/readme"
}