AppMetrica MCP — Yandex App Metrica MCP server for Claude and AI agents

MCP server for AppMetrica — Yandex's mobile analytics platform. Gives Claude direct access to your app's analytics: reports, funnels, dashboards, raw event logs, crash data, and push notification campaigns — and can create funnels and segments in AppMetrica itself.

Update 0.3.0 (October 2026). The server now builds analytics in AppMetrica, not only reads it: saved funnels and segments through the Management API, and real workspaces/dashboards through an experimental logged-in Chrome session (web_* tools, one-time npx appmetrica-mcp login). Also new: time series (get_report_bytime), a docs-derived catalogue of 197 metrics, all 13 Logs API tables, audit_events and the analytics_setup workflow prompt. Full list in CHANGELOG.md.

Why

AppMetrica keeps mobile product analytics (users, sessions, events, funnels, retention, revenue, crashes) behind a web UI and several HTTP APIs. This MCP server puts all of it behind one set of tools, so an AI agent such as Claude can answer and act on questions like:

• "How did DAU, new users and crash-free sessions change this week?"
• "Build a funnel from first launch to purchase and save it in AppMetrica."
• "Which events does the app send, which ones are dead, and what is missing for a registration funnel?"
• "Create a workspace with audience, revenue and funnel widgets for the marketing team."
• "Export raw purchase events for September and compare countries."

It works with Claude Code, Claude Desktop and any other MCP client, and is listed in the official MCP Registry as io.github.pavellunev/appmetrica-mcp.

Features

• Reporting API — aggregated metrics (users, sessions, revenue, crashes, events, ...) with dimension breakdowns, time series (bytime), filters, sorting and sampling control
• Funnels — step-by-step funnel reports for saved web-UI funnels or ad-hoc steps, with absolute/relative conversion; create, update and delete saved funnels
• Dashboards & Workspaces — preset or custom widget sets computed from the Reporting API; named widget sets saved locally as workspaces
• Web session (experimental) — create and manage real AppMetrica workspaces (dashboards) and widgets through a logged-in headless Chrome session (web_* tools; the public API cannot do this)
• Segments — list saved segments and apply them to any report via segment_id; create, update and delete segments
• Event audit — audit_events compares registered events with real volumes and reports instrumentation gaps
• Workflow prompt — analytics_setup walks an agent through analysing an app, building funnels/segments/dashboards and listing instrumentation gaps
• Logs API — raw exports for all 13 tables (events, crashes, errors, installations, sessions, deeplinks, postbacks, clicks, push tokens, profiles, revenue, e-commerce, ad revenue)
• Management API — applications, event names, conversions, Logs API status
• Push API — view campaigns and statistics; create campaigns when write mode is enabled
• Safe by default — write operations (push campaigns, funnels, segments) are disabled unless you explicitly opt in

Requirements

• Node.js 22+
• An AppMetrica account with at least one application
• A Yandex OAuth token (see below)
• Optional, only for the experimental web_* tools: Google Chrome and a one-time npx appmetrica-mcp login (see Web session)

Getting an OAuth Token

Option A — one command (recommended)

npx appmetrica-mcp auth

The wizard opens a Chrome window on the Yandex consent page (the same Chrome profile the web-session tools use, so after the first time you are already logged in), you click Разрешить, and the wizard takes the confirmation code from the page URL itself — nothing to copy. The token is saved to ~/.config/appmetrica-mcp/credentials.json (mode 0600; Yandex tokens live about a year, after that just run auth again) and the server picks it up automatically — no APPMETRICA_OAUTH_TOKEN needed. At the end the wizard offers to log in to the AppMetrica web session as well (only needed for the web_* workspace tools).

Details:

• Standard OAuth 2.0 authorization-code flow with PKCE against the bundled public appmetrica-mcp OAuth app; no client secret is involved.
• Needs Google Chrome (or APPMETRICA_BROWSER_PATH / APPMETRICA_BROWSER_CHANNEL). Without it, or over SSH, use npx appmetrica-mcp auth --manual: your default browser opens the same page, Yandex shows the code and you paste it into the terminal.
• Your own Yandex OAuth app instead of the bundled one: set APPMETRICA_OAUTH_CLIENT_ID (Redirect URI https://oauth.yandex.ru/verification_code, AppMetrica read/write access). If that app also registers http://127.0.0.1:8742/callback, --loopback runs a local callback server instead of Chrome (APPMETRICA_OAUTH_PORT changes the port).
• The MCP server itself never opens a browser: if no token is found, tools answer with a short "run npx appmetrica-mcp auth" message.

Option B — paste a token yourself

Use the Russian OAuth portal (oauth.yandex.ru) — the international version (oauth.yandex.com) does not expose AppMetrica scopes in its UI.

1. Go to oauth.yandex.ru/client/new, name the app, choose Web services and set the Callback URI to https://oauth.yandex.ru/verification_code.
2. Under Доступы (Access) → AppMetrica enable Чтение данных AppMetrica (required) and Запись данных AppMetrica (optional, for write tools). Copy the ClientID.
3. Open https://oauth.yandex.ru/authorize?response_type=token&client_id=CLIENT_ID, log in, authorize, copy access_token from the redirect URL and pass it as APPMETRICA_OAUTH_TOKEN.

Tokens do not expire by default; revoke them anytime at passport.yandex.ru/profile/access. An env token always wins over the saved credentials file.

Installation

Claude Code (recommended)

claude mcp add appmetrica -- npx -y appmetrica-mcp
npx appmetrica-mcp auth   # one-time browser login (or pass -e APPMETRICA_OAUTH_TOKEN=... instead)

To enable write operations (push campaigns, creating/updating/deleting funnels and segments):

claude mcp add appmetrica \
  -e APPMETRICA_ALLOW_WRITE=true \
  -- npx -y appmetrica-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "appmetrica": {
      "command": "npx",
      "args": ["-y", "appmetrica-mcp"],
      "env": {
        "APPMETRICA_ALLOW_WRITE": "true"
      }
    }
  }
}

Building from source

git clone https://github.com/pavellunev99/app_metrica_mcp
cd app_metrica_mcp
npm install
npm run build

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | APPMETRICA_OAUTH_TOKEN | No | — | Yandex OAuth token; optional when npx appmetrica-mcp auth saved one (env wins) | | APPMETRICA_CREDENTIALS_FILE | No | ~/.config/appmetrica-mcp/credentials.json | Where auth stores the token | | APPMETRICA_OAUTH_CLIENT_ID | No | bundled public app | Your own Yandex OAuth app ClientID for auth | | APPMETRICA_OAUTH_PORT | No | 8742 | Port of the auth --loopback callback server (ignored by the default Chrome flow) | | APPMETRICA_ALLOW_WRITE | No | false | Set to true to enable write tools: push campaign creation, funnel and segment create/update/delete | | APPMETRICA_WORKSPACES_FILE | No | ~/.config/appmetrica-mcp/workspaces.json | JSON file where local workspaces (saved dashboard widget sets) are stored | | APPMETRICA_BROWSER_PROFILE | No | ~/.config/appmetrica-mcp/chrome-profile | Chrome profile directory that holds the Yandex login for the experimental web_* tools | | APPMETRICA_BROWSER_PATH | No | — | Path to a Chrome/Chromium executable (overrides the channel) | | APPMETRICA_BROWSER_CHANNEL | No | chrome | Browser channel for the web session: chrome, chromium, msedge, ... | | APPMETRICA_BROWSER_IDLE_MS | No | 120000 | Idle time after which the headless web session closes Chrome and frees the profile (so login can run) |

Available Tools

Management

| Tool | Description | |---|---| | list_applications | List all AppMetrica applications in your account | | get_application | Get details for a specific application by ID | | list_events | List client event names of an application (use them as funnel steps) | | list_conversions | List configured conversions (attributed events) | | get_logs_api_status | Check whether the Logs API is enabled for the account |

Reporting

| Tool | Description | |---|---| | get_report | Aggregated metrics for a date range, with filters, sort, segment_id, currency, accuracy, include_undefined, lang, offset | | get_report_bytime | The same as a time series (group: day / week / month / hour / all). One namespace prefix per call | | get_drilldown | Drill down into a dimension value for detailed breakdown | | list_metrics | Metric/dimension catalogue (197 metrics, 188 dimensions): compact overview, or search / namespace / kind / limit for entries | | audit_events | Event instrumentation audit for a period: registered vs active vs zero-volume events, optional expected_events, plain-language findings (read-only) |

Segments

| Tool | Description | |---|---| | list_segments | List saved segments (id, name, expression) | | get_segment | Get one segment with all fields |

Funnels

| Tool | Description | |---|---| | list_funnels | List saved funnels with decoded steps and options | | get_funnel_report | Per-step devices and conversion for a saved funnel (funnel_id) or ad-hoc steps |

Dashboards & Workspaces

| Tool | Description | |---|---| | get_dashboard | Run preset widgets (widgets) or a saved workspace (workspace) for a date range | | list_dashboard_presets | List preset widgets with their metrics | | list_workspaces | List locally saved workspaces | | get_workspace | Get a workspace with its widget specs | | save_workspace | Create or update a local workspace (local file only) | | delete_workspace | Delete a local workspace (local file only) |

Web session (experimental)

Unofficial tools that drive the AppMetrica web UI's internal API through a logged-in headless Chrome — see Web session. Every tool needs npx appmetrica-mcp login once; tools marked Write also need APPMETRICA_ALLOW_WRITE=true.

| Tool | Access | Description | |---|---|---| | web_session_status | Read | Check the web session: logged in, Yandex login, profile directory | | web_list_workspaces | Read | List the app's AppMetrica workspaces (system + custom) | | web_get_workspace | Read | One workspace: groups, headers and widgets with names, metrics, dimensions | | web_list_widget_presets | Read | Web preset widgets (widget_id = preset value), optional category | | web_list_report_namespaces | Read | Report namespaces with their Reporting API prefix; with namespace_id the valid metrics and dimensions | | web_create_workspace | Write | Create a workspace with groups ({header?, widgets?}) in one call | | web_add_widgets | Write | Add a row of widgets to a workspace (position optional) | | web_add_header | Write | Add a section header row | | web_rename_workspace | Write | Rename a workspace | | web_remove_widget | Write | Remove a widget by dashboard_widget_id | | web_delete_workspace | Wri