yandex-metrica-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| YANDEX_METRIKA_TOKEN | No | Static OAuth token for Yandex Metrica API (alternative to interactive login) | |
| YANDEX_OAUTH_CLIENT_ID | No | Your own OAuth client ID (optional, to use your own app) | |
| YANDEX_METRIKA_COUNTER_ID | Yes | Your Yandex Metrica counter ID | |
| YANDEX_OAUTH_CLIENT_SECRET | No | Your own OAuth client secret (optional, required if using own client ID) |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Yandex Metrica analytics. Start with get_metadata (counters) and describe_counter (goals, filters). Rules for correct conclusions:
The API counts robots by default: add ym:s:isRobot=='No' (ym:pv:isRobot=='No' for hits) to filters, joined with AND.
Compare complete, like-for-like periods: end on yesterday (today is partial), equal lengths with the same weekday mix.
If meta.sampled is true and the number drives a decision, re-run with accuracy="full" and say it was sampled.
users, rates and averages are not additive: never sum daily or per-row users — take totals from one query over the whole period.
Build conversions from explicit goal ids (ym:s:goalreaches/conversionRate). Avoid "any goal" metrics and auto-goals ("Автоцель:") unless asked.
Keep one attribution family (lastsign* by default) per analysis and name it.
A metric or goal dropping to ~0 while visits stay flat is usually a tracking break, not behaviour — check goals, chart annotations and recent deploys.
Show absolute counts next to percentages; changes on ~100 visits or ~20 conversions are noise.
Name the counter, periods, filters, attribution and sampling in the answer; every number must come from a tool result.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| loginA | 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_codeA | Complete a copy-paste sign-in started by login: pass the code Yandex showed you after you approved access. |
| get_metadataA | 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_counterA | Read a single counter's configuration — settings, goals, segments, filters, operations and access grants and chart annotations — choosing sections with |
| run_reportA | 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_comparisonA | 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_drilldownA | 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_timeseriesA | 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_requestA | 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_statusA | 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_downloadA | 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_cleanA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 12 tools
Each tool has a distinct role: authentication, counter discovery/config, four reporting shapes, and the Logs API lifecycle. The reporting tools are clearly differentiated by output shape (flat rows, A/B comparison, tree drilldown, time series), and the metadata/counter-config split is explicitly cross-referenced.
Most names follow predictable patterns within workflow groups: run_* for reports, logs_* for log-request lifecycle, and verb_noun for get_metadata, describe_counter, and submit_code. The lone outliers are login and the noun-prefixed logs_* group, but they remain readable and conventional.
Twelve tools is well scoped for auth, discovery, reporting, and Logs API workflows. Each tool earns its place, with no obvious redundant variants or thin single-purpose surface.
The set covers the full practical lifecycle: sign-in with fallback, counter discovery and configuration, multiple report modalities, and log request/status/download/clean operations. No obvious dead ends are visible for the stated Yandex Metrica analytics purpose.