ya-metrics-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ya-metrics-mcp List my Metrika counters"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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_codeData access — add
metrika:read(this is the only scope needed for all 31 tools)
Click Create application and copy the ClientID.
Open this URL in your browser (replace
<ClientID>with your value):https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>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 runinstead:{ "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 all counters on the account (use this first to find counter IDs) |
| List conversion goals for a counter (call before |
| Counter metadata: name, site, timezone, permissions |
Traffic & Sources
Tool | Description |
| Visit statistics with date range (defaults to 7 days) |
| Traffic sources overview |
| Top search phrases |
| Breakdown by source type (organic, direct, referral) |
| Sessions by search engine, with robot/new-user filters |
| New user acquisition by traffic source (defaults to 30 days) |
Content Analytics
Requires Yandex Zen/Turbo publisher integration on the counter.
Tool | Description |
| Sources driving readers to articles |
| Stats by content category |
| Author performance |
| Performance by topic |
| Top articles by views |
Demographics & Devices
Tool | Description |
| Age, gender, device breakdown |
| Browser and OS analysis |
| Mobile vs desktop comparison |
| Sessions by page depth |
Geographic
Tool | Description |
| Traffic by city (all cities by default, or filter by name) |
| Organic traffic by country and city |
Performance & Conversion
Tool | Description |
| Bounce rate and duration by entry URL path |
| Conversion rates for specified goals |
| SEO performance by query and engine |
| Conversion by source × landing page URL |
Advanced & Drill-Down
Tool | Description |
| E-commerce purchases by product name (requires e-commerce tracking) |
| Time-series data with custom grouping |
| A/B experiment bounce rates |
| Browser usage report |
| Single branch of a hierarchical tree-view report |
| Compare two user segments side by side |
| 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 OAuth token |
|
| Request timeout in seconds | |
|
| Retry attempts for 5xx errors | |
|
| Base delay between retries (seconds) | |
|
| Restrict to read-only 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/.envInstallation
From PyPI:
uvx ya-metrics-mcpFrom source:
git clone https://github.com/mrkhachaturov/ya-metrics-mcp
cd ya-metrics-mcp
uv sync
uv run ya-metrics-mcpDevelopment
# Install with dev dependencies
uv sync --extra dev
# Run tests
uv run pytest
# Lint
uv run ruff check src/License
MIT
Available Tools
31 toolscompare_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
Scored across 31 tools
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 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.
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.
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
Related MCP Connectors
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Read-only Google Analytics 4 MCP server for AI assistants.
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseAqualityCmaintenanceMCP server for Yandex AppMetrica analytics, enabling Claude to access reports, raw event logs, crash data, and push notification campaigns.11207 npm3MIT
- AlicenseAqualityBmaintenanceMCP 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.8708 npm5MIT
- AlicenseAqualityCmaintenanceA local MCP server that connects Yandex Direct advertising reports and safe campaign creation to AI agents, enabling natural-language analytics and protected campaign setup.82MIT