# @rezlazy/yandex-metrika-mcp

MCP server for [Yandex Metrika Reports API](https://yandex.ru/dev/metrika/ru/stat/) (`/stat/v1/*`) and [Management API](https://yandex.ru/dev/metrika/ru/management/) (`/management/v1/*`).

Exposes **68 tools**: 6 report tools and 62 management tools (counters, goals, filters, grants, segments, labels, and more).

## Requirements

- Node.js 20+
- OAuth token with `metrika:read` (reports) and/or `metrika:write` (create/update/delete)

## Getting an OAuth token

1. [Create a Yandex OAuth app](https://oauth.yandex.ru/?dialog=create-client-entry) — choose **For API access or debugging**.
2. Add permissions **metrika:read** (reports) and **metrika:write** (management changes).
3. Copy the app **Client ID**.
4. Open in browser:

   ```
   https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>
   ```

5. Copy the token from the redirect URL (`access_token=...`).

See [Yandex Metrika authorization docs](https://yandex.ru/dev/metrika/ru/intro/authorization.md).

## Cursor configuration

Add to `.cursor/mcp.json` or Cursor MCP settings:

From GitHub (builds `dist` via `prepare` on install):

```json
{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "github:Rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}
```

The default branch includes `prepare`. Pin a release with `github:Rezlazy/yandex-metrika-mcp#v0.2.2` (`v0.2.0` does not build from git).

For local development (`.cursor/mcp.json` in this repo):

```json
{
  "mcpServers": {
    "yandex-metrika": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
```

Create `.env` in the project root:

```env
METRIKA_TOKEN=your_oauth_token
```

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `METRIKA_TOKEN` | yes | OAuth token (`metrika:read` / `metrika:write`) |
| `METRIKA_API_URL` | no | API base URL (default: `https://api-metrika.yandex.net`) |

### Multi-root workspace (`*.code-workspace`)

If you open `mcp.code-workspace` (several folders in one window), Cursor may **not show** project MCP servers from `.cursor/mcp.json` in Settings → MCP. This is a [known Cursor limitation](https://forum.cursor.com/t/project-cursor-mcp-json-not-loaded-in-multi-root-code-workspace/167648).

**Workarounds:**

1. **Open this repo directly:** File → Open Folder → `yandex-metrika-mcp` (not the `.code-workspace` file).
2. **Or add to global config** `~/.cursor/mcp.json` (works in multi-root):

```json
"yandex-metrika": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/yandex-metrika-mcp/dist/index.js"],
  "envFile": "/absolute/path/to/yandex-metrika-mcp/.env"
}
```

After config changes: **Refresh** MCP in settings or restart Cursor. Check logs: Output panel → **MCP Logs**.

## Tools

### Reports (`stat_*`) — 6 tools

| Tool | Description |
|------|-------------|
| `stat_data` | Table report |
| `stat_bytime` | Time series (charts, trends) |
| `stat_drilldown` | Tree / drill-down report |
| `stat_comparison` | Compare two segments (A vs B) |
| `stat_comparison_drilldown` | Segment comparison with drill-down |
| `stat_pivot` | Pivot table |

### Management (`mgmt_*`) — 62 tools

Covers [Management API](https://yandex.ru/dev/metrika/ru/management/): counters, goals, filters, operations, grants, access filters, segments, chart annotations, labels, accounts, delegates, clients, cloud exports.

Common management tools:

| Tool | Description |
|------|-------------|
| `mgmt_counters_list` | List available counters |
| `mgmt_counter_get` | Get counter details |
| `mgmt_counter_create` | Create counter |
| `mgmt_goals_list` | List counter goals |
| `mgmt_goal_create` | Create goal |
| `mgmt_grants_list` | List access grants |
| `mgmt_segments_list` | List saved segments |

For POST/PUT methods pass JSON in the **`body`** parameter (see [API formats](https://yandex.ru/dev/metrika/ru/management/formats.md)). Example for creating a counter:

```json
{
  "body": {
    "counter": {
      "name": "My site",
      "site": "example.com"
    }
  }
}
```

### Report parameters

- **ids** — counter ID(s), comma-separated
- **metrics** — e.g. `ym:s:visits`, `ym:s:users`, `ym:s:pageviews`
- **dimensions** — e.g. `ym:s:trafficSource`, `ym:s:operatingSystem`
- **date1** / **date2** — period (`7daysAgo`, `today`, or `YYYY-MM-DD`)
- **filters** — [segmentation expression](https://yandex.ru/dev/metrika/ru/stat/segmentation.md)
- **preset** — [report preset](https://yandex.ru/dev/metrika/ru/stat/presets.md)
- **format** — `json` (default) or `csv`

Full list of metrics and dimensions: [attrandmetr](https://yandex.ru/dev/metrika/ru/stat/attrandmetr/dim_all.md).

### Example: visits by traffic source

Tool: `stat_data`

```json
{
  "ids": "44147844",
  "metrics": "ym:s:visits,ym:s:users",
  "dimensions": "ym:s:trafficSource",
  "date1": "30daysAgo",
  "date2": "today",
  "sort": "-ym:s:visits",
  "limit": "10"
}
```

### Example: daily visits trend

Tool: `stat_bytime`

```json
{
  "ids": "44147844",
  "metrics": "ym:s:visits",
  "date1": "30daysAgo",
  "date2": "today",
  "group": "day"
}
```

## Development

```bash
npm install
npm run typecheck
npm test
npm run build
```

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

## License

MIT