@rezlazy/yandex-metrika-mcp

MCP server for Yandex Metrika Reports API (/stat/v1/*) and Management API (/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)

Related MCP server: Yandex Direct MCP

Getting an OAuth token

1. Create a Yandex OAuth app — 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.

Cursor configuration

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

From GitHub (builds dist via prepare on install):

{
  "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):

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

Create .env in the project root:

METRIKA_TOKEN=your_oauth_token

Environment variables

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.

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

"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

Management (mgmt_*) — 62 tools

Covers Management API: counters, goals, filters, operations, grants, access filters, segments, chart annotations, labels, accounts, delegates, clients, cloud exports.

Common management tools:

For POST/PUT methods pass JSON in the body parameter (see API formats). Example for creating a counter:

{
  "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

• preset — report preset

• format — json (default) or csv

Full list of metrics and dimensions: attrandmetr.

Example: visits by traffic source

Tool: stat_data

{
  "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

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

Development

npm install
npm run typecheck
npm test
npm run build

Changelog

See CHANGELOG.md.

License

MIT