Skip to main content
Glama

ya-metrics-mcp

License Python FastMCP

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"

Related MCP server: appmetrica-mcp

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

Available Tools

31 tools
compare_segmentsB

Compare two user segments side by side in a table report.

Inputs: counter_id (required), metrics (required), dimensions (required), segment_a_name (required), +6 more. Returns: result

compare_segments_drilldownC

Compare two segments in a hierarchical tree-view report with drill-down capability.

Inputs: counter_id (required), metrics (required), dimensions (required), segment_a_name (required), +7 more. Returns: result

get_account_infoB

Get basic account and counter information from Yandex Metrika.

Inputs: counter_id (required). Returns: result

get_browsers_reportB

Get browsers report without accounting for browser version.

Inputs: counter_id (required). Returns: result

get_content_analytics_articlesC

Get detailed report on article views grouped by article.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_content_analytics_authorsC

Get statistics on article authors performance.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_content_analytics_categoriesC

Retrieve overall statistics by content category.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_content_analytics_sourcesB

Get sources that drive users to website articles.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_content_analytics_topicsC

Analyze performance by article topics.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_conversion_rate_by_source_and_landingB

Get conversion rate analysis by traffic source and landing page.

Inputs: counter_id (required), goal_id (required), date_from, date_to. Returns: result

get_data_by_timeC

Get data for specific time periods grouped by day/week/month/quarter/year.

Inputs: counter_id (required), metrics (required), date_from, date_to, +4 more. Returns: result

get_device_analysisC

Analyze user behavior by browser and operating system.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_drilldownB

Generate a single branch of a hierarchical tree-view report (drill-down).

Inputs: counter_id (required), dimensions (required), metrics (required), parent_id, +3 more. Returns: result

get_ecommerce_performanceB

Get e-commerce performance by product category and region.

Inputs: counter_id (required), currency, date_from, date_to. Returns: result

get_geographical_organic_trafficB

Analyze geographical distribution of organic traffic.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_goals_conversionC

Track conversion rates for specified goals.

Inputs: counter_id (required), goal_ids (required). Returns: result

get_mobile_vs_desktopC

Compare traffic and engagement metrics between mobile and desktop users.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_new_users_by_sourceC

Identify which traffic sources are most effective in acquiring new users.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_organic_search_performanceC

Analyze organic search performance by search engine and query.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_page_depth_analysisC

Get sessions where users viewed more than the specified number of pages.

Inputs: counter_id (required), min_pages. Returns: result

get_page_performanceC

Get page performance and bounce rate by URL path.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_regional_dataC

Get sessions and users data for specific regions/cities.

Inputs: counter_id (required), cities. Returns: result

get_search_engines_dataB

Get sessions and users data from search engines with optional filters.

Inputs: counter_id (required), exclude_robots, new_users_only. Returns: result

get_traffic_sources_typesB

Analyze different types of traffic sources (organic, direct, referral).

Inputs: counter_id (required). Returns: result

get_user_demographicsB

Access user demographics and engagement by device category.

Inputs: counter_id (required), date_from, date_to. Returns: result

get_visitsB

Retrieve visit statistics with optional date range (defaults to last 7 days).

Inputs: counter_id (required), date_from, date_to. Returns: result

get_yandex_direct_experimentC

Get bounce rate for specific Yandex Direct A/B experiments.

Inputs: counter_id (required), experiment_id (required). Returns: result

list_countersA

List all Yandex Metrika counters available to this account. Use this to find counter IDs.

Inputs: search, per_page. Returns: result

list_goalsA

List all conversion goals configured for a counter. Use goal IDs with get_goals_conversion.

Inputs: counter_id (required). Returns: result

sources_search_phrasesB

Retrieve search phrases and browser information from traffic sources.

Inputs: counter_id (required). Returns: result

sources_summaryC

Get comprehensive traffic sources overview and summary report.

Inputs: counter_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 31 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but some overlap exists (e.g., get_browsers_report vs get_device_analysis both deal with browser information). Descriptions generally help differentiate them.

    Naming Consistency3/5

    Naming is mixed: most tools use get_<noun>, but there are list_ and compare_ prefixes, and anomalies like sources_search_phrases. The pattern is inconsistent but still readable.

    Tool Count2/5

    With 31 tools, the surface is too large for a focused analytics server. Many tools are granular, increasing risk of agent misselection and making the tool set feel bloated.

    Completeness4/5

    Core analytics areas are well-covered: traffic sources, content, e-commerce, goals, devices, geography. Minor gaps exist (e.g., no funnel or path analysis), but the set is largely complete for standard reporting.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides access to Yandex Metrika analytics data through various tools and functions. This server allows AI assistants and applications to retrieve comprehensive analytics data from Yandex Metrika accounts.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Yandex AppMetrica analytics, enabling Claude to access reports, raw event logs, crash data, and push notification campaigns.
      11
      207 npm
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Yandex Metrica analytics: query web analytics metrics, goals, conversions, and raw API data using natural language from AI clients like Claude and Cursor.
      8
      708 npm
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A local MCP server that connects Yandex Direct advertising reports and safe campaign creation to AI agents, enabling natural-language analytics and protected campaign setup.
      8
      2
      MIT