# ya-metrics-mcp

![License](https://img.shields.io/github/license/mrkhachaturov/ya-metrics-mcp)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![FastMCP](https://img.shields.io/badge/FastMCP-2.13%2B-green)

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 `<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:

```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