ya-metrics-mcp

Model Context Protocol (MCP) server for Yandex Metrika analytics. Exposes 31 analytics tools to your AI assistant — traffic, content, demographics, geographic, conversion, e-commerce data, and hierarchical drill-down reports.

Documentation in Russian is available here / Документация на русском языке — здесь.

Quick Start

1. Get Your OAuth Token

1. Go to oauth.yandex.ru/client/new and create a new application:

   • Name — any name you like

   • Platforms — select Web services

   • Redirect URI — enter https://oauth.yandex.ru/verification_code

   • Data access — add metrika:read (this is the only scope needed for all 31 tools)

2. Click Create application and copy the ClientID.

3. Open this URL in your browser (replace <ClientID> with your value):

   https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>

4. Authorize and copy the token from the resulting page.

2. Configure Your IDE

Add to your Claude Desktop / Cursor MCP configuration:

{
  "mcpServers": {
    "ya-metrics": {
      "command": "uvx",
      "args": ["ya-metrics-mcp"],
      "env": {
        "YANDEX_API_KEY": "your_oauth_token"
      }
    }
  }
}

Running from source? Use uv run instead:

{
  "mcpServers": {
    "ya-metrics": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ya-metrics-mcp", "ya-metrics-mcp"],
      "env": { "YANDEX_API_KEY": "your_oauth_token" }
    }
  }
}

3. Start Using

Ask your AI assistant to:

• "List my Metrika counters" — start here to find your counter ID

• "Show me visits for counter 12345678 over the last 30 days"

• "What are the top traffic sources for my site?"

• "Compare mobile vs desktop users this month"

• "Show conversion rates for goals 1 and 2"

• "Drill down into traffic by country → city"

• "Compare organic vs direct traffic segments"

Tools

31 tools across 7 domains:

Account & Counters

Traffic & Sources

Content Analytics

Requires Yandex Zen/Turbo publisher integration on the counter.

Demographics & Devices

Geographic

Performance & Conversion

Advanced & Drill-Down

Response Size Control

Many tools accept a limit parameter to cap the number of rows returned. This is useful when working with AI assistants to keep responses within context limits. Tools with limit support: sources_summary, sources_search_phrases, get_device_analysis, get_page_performance, get_organic_search_performance, get_conversion_rate_by_source_and_landing, get_regional_data, get_geographical_organic_traffic, get_drilldown, compare_segments, compare_segments_drilldown.

Configuration

All configuration via environment variables:

Copy .env.example to .env and fill in your values.

CLI

# stdio (default, for MCP clients)
ya-metrics-mcp

# HTTP transport
ya-metrics-mcp --transport streamable-http --port 8000

# With verbose logging
ya-metrics-mcp -vv

# Load custom .env file
ya-metrics-mcp --env-file /path/to/.env

Installation

From PyPI:

uvx ya-metrics-mcp

From source:

git clone https://github.com/mrkhachaturov/ya-metrics-mcp
cd ya-metrics-mcp
uv sync
uv run ya-metrics-mcp

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/

License

MIT