@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: Google Analytics MCP Server

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

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

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