Yandex Metrica MCP server

yandex-metrica-mcp

Read-only MCP server for the Yandex Metrica Reporting API and Logs API, designed for use with Claude Code and Codex CLI.

Runs locally over stdio. No web server, no persistent storage, no background daemons.

Why this project exists

Yandex Metrica has two distinct APIs that serve different purposes:

• Reporting API (/stat/v1/data) — aggregated, sampled statistics. Use this to build reports, query traffic sources, behavior metrics, goal conversions, etc.
• Logs API (/management/v1/counter/{id}/logrequests) — raw, non-aggregated event export. Use this when you need row-level session or hit data for custom analytics pipelines.

This MCP server exposes both APIs as named tools that an LLM can call directly.

Features

• 13 MCP tools covering counter management, goals, reporting, and full Logs API lifecycle
• Authentication via environment variable only (no interactive OAuth)
• Minimal transformation — responses stay close to the Yandex API format
• Safe download behavior: logs parts default to 50KB preview + metadata
• Strict TypeScript, zod validation, clean error messages
• Multi-stage Docker image (node:24-alpine)
• Unit + mock integration tests, live test scaffolding
• GitHub Actions CI and Docker workflows

Supported MCP Tools

Counter Management

Reporting API (aggregated)

For period comparison, pass date1b/date2b to yandexmetricagetreport. The tool automatically routes to /stat/v1/data/comparison; date1/date2 become segment A, date1b/date2_b become segment B. Each result row returns metrics: { a, b }.

Logs API (raw export)

Logs API Workflow

evaluate → create → [poll get until status=processed] → download parts → clean

The Logs API is asynchronous. After creating a request, poll yandexmetricagetlogsrequest until status = "processed", then download each part listed in logrequestparts.

Download Behavior

Raw log parts can be hundreds of MB. By default yandexmetricadownloadlogspart returns:

{
  "mode": "preview",
  "truncated": true,
  "original_byte_size": 52428800,
  "preview_byte_size": 49980,
  "content": "ym:s:visitID\tym:s:date\t...\n..."
}

Set mode: "full" to get the entire content — only do this for small parts.

Requirements

• Node.js 24+
• Yandex OAuth token with metrika:read scope

How to get YANDEXMETRICATOKEN

Shortened. The full README is on GitHub.