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

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:

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

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

Running the MCP server

The server uses stdio (stdin/stdout), not HTTP. You do not start it like a web server — your MCP client (e.g. Cursor) spawns it as a child process.

Requirements: Node.js 20+, METRIKA_TOKEN, and a built dist/index.js (for local dev).

In Cursor (recommended)

1. Configure MCP in .cursor/mcp.json or Cursor MCP settings (see examples above).
2. Settings → MCP → Refresh, or restart Cursor.

Cursor runs node dist/index.js (local) or npx @rezlazy/yandex-metrika-mcp (npm) automatically when tools are used. Check Output → MCP Logs if something fails.

From GitHub (without npm publish)

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

For git installs, dist/ must exist in the repo or build on install (e.g. via a prepare script).

Manual run (debugging only)

npm run build
export METRIKA_TOKEN=your_oauth_token
node dist/index.js

The process waits silently for JSON-RPC on stdin — that is expected. Without METRIKA_TOKEN, it exits with an error.

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.

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)

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

Publishing to npm

Publishing is automated via GitHub Actions when a GitHub Release is published.

One-time setup:

1. Create npm organization/scope @rezlazy on npmjs.com.
2. Generate an npm Automation token.
3. Add NPM_TOKEN secret to the GitHub repository.
4. Create a release with tag v0.1.0 — the workflow publishes @rezlazy/yandex-metrika-mcp.

License

MIT