# 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mrkhachaturov-ya-metrics-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mrkhachaturov](https://agentstack.voostack.com/s/mrkhachaturov)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mrkhachaturov](https://github.com/mrkhachaturov)
- **Source:** https://github.com/mrkhachaturov/ya-metrics-mcp

## Install

```sh
agentstack add mcp-mrkhachaturov-ya-metrics-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ya-metrics-mcp

Model Context Protocol (MCP) server for [Yandex Metrika](https://metrika.yandex.ru/) 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](README_ru.md) / Документация на русском языке — [здесь](README_ru.md).

## Quick Start

### 1. Get Your OAuth Token

1. Go to [oauth.yandex.ru/client/new](https://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 `` with your value):
   ```
   https://oauth.yandex.ru/authorize?response_type=token&client_id=
   ```

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

### 2. Configure Your IDE

Add to your Claude Desktop / Cursor MCP configuration:

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

> **Running from source?** Use `uv run` instead:
> ```json
> {
>   "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

```bash
# 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:**
```bash
uvx ya-metrics-mcp
```

**From source:**
```bash
git clone https://github.com/mrkhachaturov/ya-metrics-mcp
cd ya-metrics-mcp
uv sync
uv run ya-metrics-mcp
```

## Development

```bash
# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mrkhachaturov](https://github.com/mrkhachaturov)
- **Source:** [mrkhachaturov/ya-metrics-mcp](https://github.com/mrkhachaturov/ya-metrics-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mrkhachaturov-ya-metrics-mcp
- Seller: https://agentstack.voostack.com/s/mrkhachaturov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.