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