# Yandex Metrica MCP

> Yandex Metrica MCP is an open-source MCP server for analytics and data. Query Yandex Metrica traffic, conversions and raw logs from AI, read-only by default. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/boxlab-ltd/yandex-metrica-mcp
- **MCP Registry name:** io.github.BoxLab-Ltd/yandex-metrica-mcp
- **Categories:** [analytics and data](https://ai-powered.com/categories/analytics-and-data), [marketing and SEO](https://ai-powered.com/categories/marketing-and-seo)
- **Listing updated:** 2026-11-18

## About

A community-built server, since the README says Yandex offers no official Metrica one. It runs through npx on Node.js 18 or later and wraps the Reporting API so an assistant can ask about traffic sources, landing pages, goals, geography, devices and trends. It is built to keep model context small: field selection is on by default, row limits are low, and sampling and quota information is passed back.

Login is interactive. Running the auth command opens the Yandex consent page and returns the code over a local loopback redirect using PKCE, so no client secret is stored; the token is cached for about a year. A static token also works for CI. Raw session or hit exports go through an asynchronous request, poll, download and clean cycle, returning a bounded sample or streaming the full export to a file.

Write tools stay off unless YANDEX_METRIKA_ENABLE_WRITE is set to 1. They add chart annotations and ad-expense CSV upload, and each change is confirmed by the user first. An optional local HTTP mode listens on 127.0.0.1 only. The server also hands clients short analysis rules, such as excluding robots and comparing complete periods.

## Features

- **Flexible reports:** Run reports, period comparisons, drilldowns and time series against Metrica counters.
- **Raw log export:** Request, poll, download and clean session or hit exports without flooding context.
- **Counter inspection:** Read goals, segments, filters and annotations for a counter.
- **Opt-in write tools:** Manage chart annotations and upload ad expenses, each confirmed before sending.
- **PKCE sign-in:** Browser login with no client secret stored on the machine.
- **Local HTTP mode:** Serve several clients from one local instance bound to loopback.

## Good for

- Ask which traffic sources grew over the last 7 days
- Compare conversions between two periods
- Export un-sampled visit logs to a file for analysis
- Pin a release or campaign date as a chart annotation
- Import ad costs from another network to see ROI

## Install

### Claude Code (Terminal)

```sh
claude mcp add yandex-metrica-mcp --env YANDEX_METRIKA_TOKEN='<YANDEX_METRIKA_TOKEN>' -- npx -y yandex-metrica-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "yandex-metrica-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "yandex-metrica-mcp"
      ],
      "env": {
        "YANDEX_METRIKA_TOKEN": "<YANDEX_METRIKA_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `run_report`: Flexible wrapper over the Metrica Reporting API.
- `run_comparison`: Compares two periods with absolute and percentage deltas.
- `run_drilldown`: Drills down through a dimension tree.
- `run_timeseries`: Returns metrics as a time series for trends.
- `get_metadata`: Lists counters on the account and a catalog of dimensions, metrics and Logs API fields.
- `describe_counter`: Reads a counter's goals, segments, filters, operations, access grants and annotations.
- `logs_request`: Starts a raw Logs API export of visits or hits.
- `logs_status`: Checks the status of a Logs API export.
- `logs_download`: Downloads an export as a bounded inline sample or a file.
- `logs_clean`: Cleans up a finished Logs API export.
- `login`: Signs in to Yandex Metrica from the MCP client.
- `submit_code`: Completes sign-in with a pasted authorization code.
- `manage_annotation`: Creates, updates or deletes a chart annotation (write mode only).
- `upload_expenses`: Imports ad costs from a CSV file, with a dry-run option (write mode only).

## FAQ

### Is it an official Yandex product?

No. The README says there is no official Yandex Metrica MCP server and this is an independent open option.

### Can it change my data?

Only if you set YANDEX_METRIKA_ENABLE_WRITE=1, and each change is confirmed first.

### How do I sign in?

Run npx yandex-metrica-mcp auth and approve access in the browser, or supply a static OAuth token.

### What does it need?

Node.js 18 or later and Yandex credentials with the metrika:read scope.

### Is Yandex Metrica MCP free?

Yes. Yandex Metrica MCP is open source, so you can use and self-host it for free.

### How do I add Yandex Metrica MCP to Claude Code?

Run this command in your terminal: claude mcp add yandex-metrica-mcp --env YANDEX_METRIKA_TOKEN='<YANDEX_METRIKA_TOKEN>' -- npx -y yandex-metrica-mcp

### What are the best alternatives to Yandex Metrica MCP?

The closest alternatives to Yandex Metrica MCP are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, dashboard-icons, Tapetide - Indian Stock Market MCP and World Monitor.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [dashboard-icons](https://ai-powered.com/mcp/dashboard-icons): dashboard-icons is an open-source MCP server for analytics and data.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [World Monitor](https://ai-powered.com/mcp/world-monitor): World Monitor is a freemium MCP server for analytics and data.
- [Calven](https://ai-powered.com/mcp/calven): Calven is an MCP server for marketing and seo.
- [DataArcus for Power BI](https://ai-powered.com/mcp/dataarcus-for-power-bi): DataArcus for Power BI is a free MCP server for analytics and data.
- [CompanyData](https://ai-powered.com/mcp/companydata): CompanyData is a paid MCP server for analytics and data.

---
Source: https://ai-powered.com/mcp/yandex-metrica-mcp
