Яндекс Метрика MCP

Яндекс Метрика MCP connects an AI application to your website's web analytics. Ask in natural language where visitors come from, how conversion changes, or where the bounce rate is growing — the assistant will pull data from your counter and explain the result. Connection starts right in the conversation: no need to create a token or edit configuration in advance.

• Eight tools. Metrica counters, goals, and reports, connecting and disconnecting access, plus one universal API request.

• Reports and conversions. Visits, users, pageviews, bounces, visit duration, sources, devices, and goals for a selected period.

• Connection in chat. Yandex opens a login page; the one-time code is valid for 10 minutes, and the server checks access to counters right after connection.

• Regular requests are read-only. Specialized tools do not change counters, goals, or Metrica data.

• No silent truncation. The report shows totals and a sampling flag; when the result is large, the server notes if it hit the limit.

Try with your first message:

How many visits, users, and bounces did my site have in the last week?

Connect server · See scenarios · Open technical documentation

See it work in a minute

You: Connect Яндекс Метрику.

Assistant: Gives a link to sign in to Yandex. Open it under an account that has access to the needed counters, confirm access, and send back the shown code.

You: Sends the code from the Yandex page.

Assistant: Connects Metrica, checks whether counters are visible, and reports the result. No need to restart the application.

You: For the last 30 days, show traffic sources and conversion for the “Checkout” goal.

Assistant: Finds the goal, builds a report by sources, and shows visits, goal achievements, and conversion. If Metrica applied sampling, it notes that the numbers are approximate.

Related MCP server: ya-metrics-mcp

Contents

• Quick start

• What you can ask for

• How it works

• What can change data

• Connection and configuration

• Data and telemetry

• Limitations

• Technical documentation

• Support

Quick start

You need Node.js 20 or newer. The server runs via npx, so no separate package installation is required.

1. Add the server to your AI application — an example for Codex is open below, other applications are collected in collapsible instructions.

2. Write: “Connect Яндекс Метрику”. The assistant will walk you through Yandex login and immediately check that it can see your counters.

3. Ask your first question, for example: “Which sources gave the most visits last month?”

Through the application interface:

1. Open Settings → Plugins → MCP servers.

2. Click Add server.

3. Add the launch command npx -y mcp-yandex-metrica@latest.

Through the command line:

codex mcp add yandex-metrica -- npx -y mcp-yandex-metrica@latest

Check the connection:

codex mcp list

Then in the Codex chat ask: “Connect Яндекс Метрику”.

Official Codex instructions

claude mcp add --transport stdio --scope user yandex-metrica -- npx -y mcp-yandex-metrica@latest

Check the server with the command:

claude mcp list

Then start the conversation by asking to connect Metrica.

Claude Code documentation

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica@latest"]
    }
  }
}

After saving, open a new conversation and ask to connect Metrica.

For all projects create ~/.cursor/mcp.json; for the current project only — .cursor/mcp.json:

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica@latest"]
    }
  }
}

In the Cursor chat, the server will appear among available tools. Ask to connect Metrica and go through Yandex login.

Cursor documentation

Open the command palette and run MCP: Open User Configuration. Add to mcp.json:

{
  "servers": {
    "yandex-metrica": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica@latest"]
    }
  }
}

Check the launch with the command MCP: List Servers, then open the chat and ask to connect Metrica.

VS Code documentation

What you can ask for

Understand what's happening with the site

• “How many visits, users, and pageviews were there in the last week?”

• “Show daily traffic dynamics for June.”

• “On which devices is the bounce rate higher?”

Find the traffic source and evaluate its quality

• “Show traffic sources for the month and sort by visits.”

• “Compare organic search and ads by users and bounces.”

• “Which sources gave the most clicks this week?”

Work with conversions

• “What goals are set up in the counter?”

• “What is the conversion for the “Checkout” goal over 30 days?”

• “Show the sources that brought the most goal achievements.”

Check access and data accuracy

• “Which counters are available to me?”

• “Show the connection status to Metrica.”

• “Are the data in this report accurate or did Metrica use sampling?”

How it works

The server works with three familiar entities:

Usually the assistant first finds an available counter, then — if needed — a goal, and only then builds a report. The Metrica response includes a total across all rows, the output size, and a sampling flag.

What can change data

The server marks an arbitrary write as a potentially destructive action. How exactly the AI application requests confirmation depends on the application itself; before such a request, check the path, method, and data.

Connection and configuration

For normal use, no token is needed in advance:

1. In the chat, ask to connect Яндекс Метрику.

2. Open the Yandex OAuth link under an account with access to the needed counters.

3. Confirm access and send the code to the assistant. It is valid for 10 minutes and is exchanged for a token only inside the running server.

The server uses PKCE: the code from the chat cannot be exchanged for a token on its own. The received token is stored locally in ~/.config/mcp-yandex-metrica/credentials.json with owner-only permissions. If a refresh token is saved, access is renewed automatically.

For CI and non-standard setups, configuration via environment variables is available:

If you use your own OAuth application, request the permission “Getting statistics, reading parameters of your own and trusted counters” (metrika:read) in it.

Data and telemetry

By default, the server sends anonymous technical telemetry: a random installation identifier, event or tool name, server version, Node.js version, OS, and information about the connected AI client. It does not include the token, counter data, tool arguments, your messages, or environment variable values.

To disable telemetry for Ask Ads MCP servers, set the environment variable:

ASKADS_TELEMETRY=0

Limitations

• Metrica sampling. On large periods or complex reports, the API may return approximate data. Check the sampled and sample_share fields; for a more accurate calculation, narrow the period or use accuracy: "full".

• Report size. A single request returns up to 10,000 rows. Automatic pagination stops at no more than 100 pages, 100,000 rows, or roughly 1 MB of data and marks an incomplete response with the _truncated field.

• Request retries. The timeout for one request is 60 seconds. The server makes up to three retries on temporary errors: for GET — on network errors, 429, and 5xx; for POST and DELETE — only on 429, to avoid repeating a modifying action. The delay respects Retry-After and does not exceed 30 seconds.

• Production data. Metrica has no sandbox. Specialized tools read data, but POST and DELETE through an arbitrary request change real objects.

• No background monitoring. The server works when called by the AI application and does not track metrics on its own. If the application supports scheduled tasks, you can set up a periodic report request in it.

Technical documentation

• MCP capabilities catalog — pages by user tasks for each tool.

• All tools — parameters, responses, and limits for each tool.

• Development documentation — project structure and working with the demo.

• Package on npm.

• Yandex Metrica API.

Support

Found a bug or missing a scenario? Create an issue or write to Telegram.