# yandex-metrica-mcp [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/BoxLab-Ltd/yandex-metrica-mcp  
**GitHub Stars:** 15  
**npm Downloads (last month):** 1111  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yandex-metrica-mcp

## Description
Query Yandex Metrica web analytics — reports, trends and metadata — via an AI agent.

## Tools
Capabilities this server exposes over MCP:

- **login** — Sign in to Yandex from here. Opens your browser to approve access; the code returns automatically over a local redirect, so this usually finishes in one call. If the local port is unavailable it returns a URL to approve and you then call submit_code with the code Yandex shows. Run this once (the token lasts ~1 year); needed before the data tools if you are not signed in yet.
- **submit_code** — Complete a copy-paste sign-in started by login: pass the code Yandex showed you after you approved access.
- **get_metadata** — Discovery tool. Lists the counters available to your token plus a curated catalog of common dimensions and metrics (Metrica has no enumeration API), attribution options and Logs API fields. Call this before run_report or logs_request to use real field names and to find a counterId. For a counter's own goals, segments, filters or grants, use describe_counter. Read-only.
- **describe_counter** — Read a single counter's configuration — settings, goals, segments, filters, operations and access grants — choosing sections with `include`. The goals section returns the goal ids needed to build conversion metrics (ym:s:goal<id>reaches / conversionRate) in run_report, so call this with include=["goals"] before any conversion question. To list the account's counters, use get_metadata. Read-only.
- **run_report** — Query a Yandex Metrica table report (/stat/v1/data): one or more metrics grouped by dimensions over a date range, with optional filter and sort. Read-only. Use get_metadata first to discover valid metric/dimension ids and the account counters.
- **run_comparison** — Compare two segments/periods (A vs B) for the same metrics and dimensions (/stat/v1/data/comparison). Returns per-metric values for A and B plus the absolute and percentage delta, computed server-side: delta = B − A (segment A is the baseline), delta_pct = (B − A) / A × 100. Defaults to last 7 days (B) vs the prior 7 days (A), so a positive delta means growth. Read-only.
- **run_drilldown** — Return one level of a hierarchical (tree) report (/stat/v1/data/drilldown). Each row has an "expandable" flag; pass parentId with the path of dimension keys to expand deeper. Requires dimensions. Read-only.
- **run_timeseries** — Return metrics split into a time series (/stat/v1/data/bytime): each metric comes back as an array of values, one per interval (day/week/month/…) over the date range. Use for trends and charts. Optionally group by dimensions (topKeys rows). Read-only.
- **logs_request** — Create a Yandex Metrica Logs API request for RAW, un-sampled rows (source="visits" sessions or "hits" events) over a date range. Checks feasibility, then queues preparation (takes minutes). Returns a request_id to poll with logs_status; then logs_download, then logs_clean. Discover field ids with get_metadata. Not read-only: preparing data consumes the counter storage quota.
- **logs_status** — Inspect a Logs API request by request_id (status, parts, size, next step), or omit request_id to list all of the counter's log requests and current storage-quota usage. Poll this after logs_request until status="processed". Read-only.
- **logs_download** — Download prepared log data for a request_id (must be status="processed"; check logs_status). Default mode "sample" returns up to maxRows parsed rows inline — cheap and bounded. Mode "file" streams the FULL export to a file and returns its path plus a small preview; the raw content (potentially millions of rows) is never loaded into context. Read-only.
- **logs_clean** — Free the counter storage quota by cleaning a finished (processed) log request, or cancel one still being prepared. Dispatches by current status. Destructive: cleaned data must be requested again to download later.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "yandex-metrica-mcp": {
    "command": "npx",
    "args": ["-y","yandex-metrica-mcp"],
    "env": {
      "YANDEX_METRIKA_COUNTER_ID": ""
    }
  }
}
```

**Requires environment variables:** `YANDEX_METRIKA_COUNTER_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What yandex-metrica-mcp does

The yandex-metrica-mcp MCP server gives an MCP-compatible client access to Yandex Metrica web analytics through read-only operations. It can retrieve traffic, sources, landing pages, conversions, geography, devices, and trend data, while keeping the query interface flexible enough for different dimensions and metrics.

The server also exposes account and counter discovery. Agents can list available counters, inspect common metric and dimension names, and read selected counter configuration such as goals, segments, filters, operations, and access grants. Goal metadata is useful when a later report needs a goal-specific conversion metric.

For raw-data workflows, the Logs API tools handle visit or hit exports. These exports are asynchronous: the client creates a request, checks its status, downloads the result, and can then clean up the request. Downloads return a bounded inline sample by default or write the complete export to a file.

## How it works

An MCP client starts the package through stdio, commonly with `npx -y yandex-metrica-mcp`. The client supplies a default counter ID through configuration, and an agent invokes the available tools with report parameters such as metrics, dimensions, periods, and filters.

The main reporting operations cover a single report, a comparison between two periods, hierarchical drilldowns, and time-series results. The server returns absolute and percentage differences for comparisons and supports repeated drilldowns by passing a parent identifier. Metadata tools help an agent discover valid names before making a query.

The yandex-metrica-mcp MCP server applies context controls intended to keep responses manageable. Field selection is enabled by default, row limits are conservative, and sampling or quota information is returned to the model. It communicates with Yandex and is read-only; planned write tools and Streamable HTTP transport are not part of the documented v0.1 feature set.

## Setup and configuration

Node.js 18 or newer is required. Add the server to the MCP client configuration with the `yandex-metrica-mcp` package and set `YANDEX_METRIKA_COUNTER_ID` when a default counter should be used. The package is published for Node, while the repository's local development workflow uses Bun.

The recommended login flow is `npx yandex-metrica-mcp auth`. It opens Yandex's consent page and normally receives the authorization code through a loopback redirect. If the loopback port is unavailable, the command can use a pasted code instead; `YANDEX_OAUTH_LOOPBACK_PORT` changes the port. The OAuth flow uses authorization-code PKCE, and the cached token is stored with mode 0600 under `~/.config/yandex-metrica-mcp/token.json`.

A client can also invoke the `login` tool, which is useful when the user has no terminal. For CI or other non-interactive environments, provide a Yandex token with the `metrika:read` scope through `YANDEX_METRIKA_TOKEN`. An optional `YANDEX_OAUTH_CLIENT_ID` selects a user-owned OAuth application, and adding `YANDEX_OAUTH_CLIENT_SECRET` enables automatic token refresh for that application.

## Tools and capabilities

The documented tools include:

- `run_report` for flexible queries against Yandex Metrica's Reporting API.
- `run_comparison` for comparing two periods with absolute and percentage deltas.
- `run_drilldown` for navigating a dimension tree.
- `run_timeseries` for splitting metrics by time intervals.
- `get_metadata` for counters and catalogs of metrics, dimensions, and Logs API fields.
- `describe_counter` for selected counter settings, including goals and access grants.
- `logs_request`, `logs_status`, `logs_download`, and `logs_clean` for asynchronous visit or hit exports.
- `login` and `submit_code` for authentication from an MCP client.

Typical uses include comparing organic conversions across weeks, identifying visitor operating systems and their versions, examining traffic sources, checking available counters, and exporting raw sessions for offline analysis.

## Limitations and notes

The project describes itself as early development, version 0.1, and work in progress. It requires credentials with the `metrika:read` scope and access to the counters being queried. Authentication tokens expire after roughly one year and may require another login.

The server is read-only by design. Logs exports consume Yandex quota during their lifecycle, so completed exports should be cleaned up when they are no longer needed. Full raw exports are written to a file rather than placed wholesale into the model context. Streamable HTTP and write operations are listed as future work, not current capabilities.

_Full upstream README: https://allmcps.com/mcp/yandex-metrica-mcp/readme_