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

| Tool | Description | |------|-------------| | list_counters | List all counters on the account (use this first to find counter IDs) | | list_goals | List conversion goals for a counter (call before get_goals_conversion) | | get_account_info | Counter metadata: name, site, timezone, permissions |

Traffic & Sources

| Tool | Description | |------|-------------| | get_visits | Visit statistics with date range (defaults to 7 days) | | sources_summary | Traffic sources overview | | sources_search_phrases | Top search phrases | | get_traffic_sources_types | Breakdown by source type (organic, direct, referral) | | get_search_engines_data | Sessions by search engine, with robot/new-user filters | | get_new_users_by_source | New user acquisition by traffic source (defaults to 30 days) |

Content Analytics

Requires Yandex Zen/Turbo publisher integration on the counter.

| Tool | Description | |------|-------------| | get_content_analytics_sources | Sources driving readers to articles | | get_content_analytics_categories | Stats by content category | | get_content_analytics_authors | Author performance | | get_content_analytics_topics | Performance by topic | | get_content_analytics_articles | Top articles by views |

Demographics & Devices

| Tool | Description | |------|-------------| | get_user_demographics | Age, gender, device breakdown | | get_device_analysis | Browser and OS analysis | | get_mobile_vs_desktop | Mobile vs desktop comparison | | get_page_depth_analysis | Sessions by page depth |

Geographic

| Tool | Description | |------|-------------| | get_regional_data | Traffic by city (all cities by default, or filter by name) | | get_geographical_organic_traffic | Organic traffic by country and city |

Performance & Conversion

| Tool | Description | |------|-------------| | get_page_performance | Bounce rate and duration by entry URL path | | get_goals_conversion | Conversion rates for specified goals | | get_organic_search_performance | SEO performance by query and engine | | get_conversion_rate_by_source_and_landing | Conversion by source × landing page URL |

Advanced & Drill-Down

| Tool | Description | |------|-------------| | get_ecommerce_performance | E-commerce purchases by product name (requires e-commerce tracking) | | get_data_by_time | Time-series data with custom grouping | | get_yandex_direct_experiment | A/B experiment bounce rates | | get_browsers_report | Browser usage report | | get_drilldown | Single branch of a hierarchical tree-view report | | compare_segments | Compare two user segments side by side | | compare_segments_drilldown | Segment comparison as a hierarchical tree-view |

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:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | YANDEX_API_KEY | ✓ | — | Yandex OAuth token | | YANDEX_TIMEOUT | | 30 | Request timeout in seconds | | YANDEX_RETRIES | | 3 | Retry attempts for 5xx errors | | YANDEX_RETRY_DELAY | | 1.0 | Base delay between retries (seconds) | | READ_ONLY_MODE | | false | Restrict to read-only tools | | ENABLED_TOOLS | | all | Comma-separated list of allowed tools |

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