Content
<!-- mcp-name: io.github.dontsovcmc/yandex-metrika -->
# Tool List
[](https://github.com/dontsovcmc/mcp-server-yandex-metrika)
MCP Server, CLI utility and Pydantic models library for [Yandex Metrika API](https://yandex.com/dev/metrika).
- **MCP Server** — integration with Claude Code, Claude Desktop and other MCP clients
- **CLI utility** — working with API from terminal, scripts and automation
- **Pydantic models** — typed API models for using in your Python programs
All data remains on your computer — token is not transmitted anywhere.
## Table of Contents
- [Capabilities](#capabilities)
- [MCP Server](#mcp-server)
- [Installation](#installation)
- [Connecting to Claude Code](#connecting-to-claude-code)
- [Connecting to Claude Desktop](#connecting-to-claude-desktop)
- [Connecting via --mcp-config](#connecting-via---mcp-config)
- [Examples](#mcp-examples)
- [CLI Utility](#cli-utility)
- [Installation](#cli-installation)
- [Usage](#cli-usage)
- [Command Examples](#command-examples)
- [Pydantic Models](#pydantic-models)
- [Installation](#library-installation)
- [Usage in your programs](#usage-in-your-programs)
- [Environment Variables](#environment-variables)
- [API Limits](#api-limits)
- [Development](#development)
- [License](#license)
## Capabilities
### Reports (Reporting API)
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_stat_data` | `stat-data` | Tabular report by metrics and dimensions |
| `ym_stat_data_bytime` | `stat-bytime` | Time-based report (grouping: hour/day/week/month) |
| `ym_stat_data_drilldown` | `stat-drilldown` | Drill down report with level reveal |
| `ym_stat_data_comparison` | `stat-comparison` | Segment/period comparison |
| `ym_stat_data_comparison_drilldown` | — | Comparison with drill down |
### Counters
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_counters` | `counters` | List of counters (search, filtering) |
| `ym_counter` | `counter` | Counter information |
| `ym_counter_create` | `counter-create` | Create counter |
| `ym_counter_update` | `counter-update` | Update counter |
| `ym_counter_delete` | `counter-delete` | Delete counter |
| `ym_counter_undelete` | `counter-undelete` | Restore deleted counter |
### Goals
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_goals` | `goals` | List of counter goals |
| `ym_goal` | `goal` | Goal information |
| `ym_goal_create` | `goal-create` | Create goal (url/number/step/action/...) |
| `ym_goal_update` | — | Update goal |
| `ym_goal_delete` | `goal-delete` | Delete goal |
### Filters
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_filters` | `filters` | List of filters |
| `ym_filter` | — | Filter information |
| `ym_filter_create` | `filter-create` | Create filter (IP, URL, referrer) |
| `ym_filter_update` | — | Update filter |
| `ym_filter_delete` | `filter-delete` | Delete filter |
### Access (Grants)
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_grants` | `grants` | List of permissions |
| `ym_grant_create` | `grant-create` | Issue permission |
| `ym_grant_update` | — | Update permission |
| `ym_grant_delete` | `grant-delete` | Delete permission |
### Operations
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_operations` | `operations` | List of operations |
| `ym_operation` | — | Operation information |
| `ym_operation_create` | `operation-create` | Create operation (cut_parameter, to_lower, ...) |
| `ym_operation_update` | — | Update operation |
| `ym_operation_delete` | `operation-delete` | Delete operation |
### Segments
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_segments` | `segments` | List of segments |
| `ym_segment` | — | Segment information |
| `ym_segment_create` | `segment-create` | Create segment |
| `ym_segment_update` | — | Update segment |
| `ym_segment_delete` | `segment-delete` | Delete segment |
### Labels
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_labels` | `labels` | List of labels |
| `ym_label_create` | `label-create` | Create label |
| `ym_label_update` | — | Update label |
| `ym_label_delete` | `label-delete` | Delete label |
| `ym_counter_label_set` | — | Bind label to counter |
| `ym_counter_label_unset` | — | Unbind label |
### Accounts and Representatives
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_accounts` | `accounts` | List of accounts |
| `ym_account_delete` | — | Delete account |
| `ym_delegates` | `delegates` | List of representatives |
| `ym_delegate_add` | `delegate-add` | Add representative |
| `ym_delegate_delete` | `delegate-delete` | Delete representative |
### Chart Annotations
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_chart_annotations` | `chart-annotations` | List of annotations |
| `ym_chart_annotation_create` | `chart-annotation-create` | Create annotation |
| `ym_chart_annotation_update` | — | Update annotation |
| `ym_chart_annotation_delete` | — | Delete annotation |
### Access Filters
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_access_filters` | — | List of access filters |
| `ym_access_filter_create` | — | Create access filter |
| `ym_access_filter_update` | — | Update access filter |
| `ym_access_filter_delete` | — | Delete access filter |
### Logs API
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_log_requests` | `log-requests` | List of log requests |
| `ym_log_request` | — | Request information |
| `ym_log_request_create` | `log-request-create` | Create request (hits/visits) |
| `ym_log_request_evaluate` | `log-request-evaluate` | Evaluate request possibility |
| `ym_log_request_clean` | — | Clean processed logs |
| `ym_log_request_cancel` | — | Cancel request |
| `ym_log_request_download` | `log-download` | Download log part (TSV) |
### Data Import
| Tool | CLI | Description |
|------------|-----|----------|
| `ym_offline_conversions_upload` | `upload-conversions` | Upload offline conversions |
| `ym_offline_conversions_uploads` | — | List of conversions uploads |
| `ym_offline_conversion_upload_info` | — | Upload info |
| `ym_calls_upload` | `upload-calls` | Upload calls |
| `ym_calls_uploads` | — | List of calls uploads |
| `ym_calls_upload_info` | — | Calls upload info |
| `ym_expenses_upload` | `upload-expenses` | Upload expenses |
| `ym_user_params_upload` | — | Upload user parameters |
## MCP Server
### Installation
#### Step 1. Get OAuth Token for Yandex Metrika
1. Register an application on [oauth.yandex.com](https://oauth.yandex.com/client/new)
2. Specify permissions: `metrika:read`, `metrika:write`
3. Get token: `https://oauth.yandex.com/authorize?response_type=token&client_id=<your_client_id>`
#### Step 2. Connect MCP Server
### Connecting to Claude Code
**Method 1: via uvx** (no package installation required)
> Requires [uv](https://docs.astral.sh/uv/) — if not installed:
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
```bash
claude mcp add yandex-metrika \
-e YANDEX_METRIKA_TOKEN=your_token \
-- uvx mcp-server-yandex-metrika
```
**Method 2: via pip**
```bash
pip install mcp-server-yandex-metrika
claude mcp add yandex-metrika \
-e YANDEX_METRIKA_TOKEN=your_token \
-- mcp-server-yandex-metrika
```
To remove:
```bash
claude mcp remove yandex-metrika
```
### Connecting to Claude Desktop
Add to configuration file:
| Client | OS | File path |
|--------|----|-------------|
| Claude Code | all | `~/.claude/settings.json` (section `mcpServers`) |
| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |
**Via uvx:**
```json
{
"mcpServers": {
"yandex-metrika": {
"command": "uvx",
"args": ["mcp-server-yandex-metrika"],
"env": {
"YANDEX_METRIKA_TOKEN": "your_token"
}
}
}
}
```
**Via pip** (after `pip install mcp-server-yandex-metrika`):
```json
{
"mcpServers": {
"yandex-metrika": {
"command": "python",
"args": ["-m", "mcp_server_yandex_metrika"],
"env": {
"YANDEX_METRIKA_TOKEN": "your_token"
}
}
}
}
```
### Connecting via --mcp-config
Connects the server only for the duration of one Claude session, without saving to settings. The token is stored in a separate `.env.mcp` file, not in the Claude config.
From a JSON string:
```bash
claude --mcp-config '{"yandex-metrika":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-metrika"]}}'
```
From a file:
```bash
claude --mcp-config ~/mcp-servers.json
```
Example `~/mcp-servers.json`:
```json
{
"yandex-metrika": {
"command": "bash",
"args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-yandex-metrika"]
}
}
```
Example `~/.env.mcp`:
```
YANDEX_METRIKA_TOKEN=your_token
```
#### Step 3. Check
Ask Claude: *«Show me the list of my Yandex Metrika counters»* — it will call `ym_counters`.
### Examples (MCP)
- «Show me the visit statistics for the last week for counter 12345678» → `ym_stat_data`
- «Create a goal "Purchase" of type url with condition contain "/thank-you"» → `ym_goal_create`
- «Download visit logs for January 2024» → `ym_log_request_create`
---
## CLI Utility
### Installation (CLI)
```bash
pip install mcp-server-yandex-metrika
```
The environment variable `YANDEX_METRIKA_TOKEN` must be set:
```bash
export YANDEX_METRIKA_TOKEN=your_token
```
Or through a file:
```bash
mcp-server-yandex-metrika --env /path/to/.env counters
```
File format is `KEY=VALUE`, one variable per line, `#`-comments.
### Usage (CLI)
Without arguments, the MCP server starts; with a command — CLI. All commands output JSON.
```bash
# Version
mcp-server-yandex-metrika --version
# Help
mcp-server-yandex-metrika --help
mcp-server-yandex-metrika <command> --help
```
### Command Examples
```bash
# Visit statistics
mcp-server-yandex-metrika stat-data --ids 12345678 --metrics ym:s:visits,ym:s:users
# Counter list
mcp-server-yandex-metrika counters --search "my site"
# Counter goals
mcp-server-yandex-metrika goals 12345678
# Create log request
mcp-server-yandex-metrika log-request-create 12345678 \
--date1 2024-01-01 --date2 2024-01-31 \
--fields "ym:s:date,ym:s:visitID" --source visits
```
---
## Pydantic Models
The package contains typed Pydantic models of all API objects. Models can be used in your Python programs for data validation and autocompletion in IDEs.
### Installation (libraries)
```bash
pip install mcp-server-yandex-metrika
```
### Usage in your programs
```python
from mcp_server_yandex_metrika.models import CounterBrief, Goal
# Data validation from API
data = {"id": 12345678, "name": "My site", "status": "Active"}
counter = CounterBrief.model_validate(data)
print(counter.name) # type-safe access to fields
# Object creation
goal = Goal(name="Purchase", type="url")
print(goal.model_dump_json())
```
All models use `extra="allow"` for forward compatibility — unknown API fields do not cause errors.
Full list of models: [`models.py`](src/mcp_server_yandex_metrika/models.py)
---
## Environment Variables
| Variable | Required | Default | Description |
|------------|:------------:|:------------:|----------|
| `YANDEX_METRIKA_TOKEN` | yes | — | OAuth token for Yandex Metrika |
| `METRIKA_TIMEOUT` | no | `30` | HTTP request timeout to API (seconds) |
| `METRIKA_FILE_TIMEOUT` | no | `60` | File download timeout (seconds) |
### Loading from a file
Instead of passing variables through `-e`, you can specify a file:
```bash
mcp-server-yandex-metrika --env /path/to/.env
```
File format is `KEY=VALUE`, one variable per line, `#`-comments.
Works in both modes: MCP server and CLI:
```bash
# MCP server
claude mcp add yandex-metrika -- mcp-server-yandex-metrika --env ~/.config/metrika.env
# CLI
mcp-server-yandex-metrika --env ~/.config/metrika.env counters
```
## API Limits
- 30 requests/second per IP
- 5000 requests/day per user
- 3 parallel requests per user
- 200 requests/5 minutes for `/stat/v1/data/`
- HTTP 420 when limits are exceeded
## Development
```bash
pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v
```
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available