io.github.pavellunev/appmetrica-mcp

Audit the client-event instrumentation of an application (read-only): compares event names registered in AppMetrica (list_events) with event volumes of a period (ym:ce:allEvents / ym:ce:devices by ym:ce:eventLabel). Each event is classified as active (has data in the period), zero_volume (registered but no data in the period) or missing (in expected_events but neither registered nor active). With expected_events (e.g. names found in the app's source code) every event carries expected=true/false, so active events with expected=false are the unexpected ones. System events (appmetrica_*, com.yandex.*) are listed separately in system_events and excluded from the counts. findings are plain-language heuristics: missing / zero-volume / low-volume (<=5 devices) events, mixed snake_case and CamelCase naming, and no event resembling first launch / onboarding, registration or purchase. Two requests: /v1/traffic/sources/events and /stat/v1/data.

Create a saved funnel in AppMetrica (visible in the web "Funnels" report and in list_funnels). Requires APPMETRICA_ALLOW_WRITE=true. Verify the steps with get_funnel_report(steps=...) first. Steps must be representable in the web funnel editor: client events (several names = any of them; at most ONE event_params entry per step, applied to every event of the step) or kind "install". Other step kinds (crash, purchase, session_start, ...) are rejected — use get_funnel_report for those ad-hoc. Options: foreground_only (default true), single_session (default false), events_between_steps (default true; false is saved as a "next"-joined pattern without funnel_restriction, which the API does not store — unverified, prefer the default). Returns {id, name, steps, pattern, next}.

Create a new push notification campaign in AppMetrica. Requires APPMETRICA_ALLOW_WRITE=true to be set.

Create a saved segment in AppMetrica (shown in the web UI; pass its segment_id to get_report / get_report_bytime / get_funnel_report / get_dashboard). Requires APPMETRICA_ALLOW_WRITE=true. Condition: events — users who did ALL the listed client events (expression "exists ym:ce:device with (eventLabel=='X')" AND-joined; editable in the web segment editor). The API derives the expression from the editor filter JSON, so other condition types (device, geo, version, profile…) must be created in the web UI; for ad-hoc filtering use the filters parameter of the report tools instead. Returns {segment_id, name, expression, edit_access}.

Delete a saved funnel from AppMetrica (irreversible). Requires APPMETRICA_ALLOW_WRITE=true.

Delete a saved segment from AppMetrica (irreversible; reports and dashboards using its segment_id will fail). Requires APPMETRICA_ALLOW_WRITE=true.

Delete a local workspace by name (local file operation only; nothing is changed in AppMetrica).

Export raw crash logs from AppMetrica for a given application and time range. Use this for per-crash-name breakdowns — get_report only exposes the total ym:cr:crashes count. Same async/rate-limit behaviour as export_events: the wrapper re-polls 202 (default ~150s budget), honours Retry-After on 429, and backs off. Run sequentially and avoid rapid retries — wide ranges may need a manual retry after a few minutes.

Export raw event logs from AppMetrica Logs API. Revenue and in-app purchase data is stored in the event_json field as structured JSON. Default fields: event_name, event_datetime, event_json, appmetrica_device_id, app_version_name, os_version, device_model, country_iso_code, city. To get subscription/purchase data: filter by event_name (e.g. "subscription_purchase") and parse event_json field. Logs API is asynchronous — the first request usually returns "data not ready" (HTTP 202) and the wrapper re-polls the same query (default budget ~150s, tunable via APPMETRICA_MAX_WAIT_MS). A busy or wide query may still need a manual retry after a few minutes; re-running the identical query resumes the same server-side export. Start with 1-day windows; multi-day exports take noticeably longer to materialise. Run export_events strictly sequentially and avoid rapid retries — the Logs API has a low export-request quota; on HTTP 429 the wrapper honours Retry-After and backs off, but exhausting the quota also blocks the AppMetrica web UI for a few minutes.

Export raw installation logs from AppMetrica for a given application and time range. Same async/rate-limit behaviour as export_events: the wrapper re-polls 202 (default ~150s budget), honours Retry-After on 429, and backs off. Run sequentially and avoid rapid retries — wide ranges may need a manual retry after a few minutes.

Export raw rows from any Logs API table: clicks, installations, postbacks, events, ecommerce_events, profiles_v2, revenue_events, ad_revenue_events, deeplinks, crashes, errors, push_tokens, sessions_starts. Field names per table come from the official AppMetrica docs; unknown fields are rejected with the list of allowed ones. Default fields = all fields of the table. date_from/date_to (YYYY-MM-DD) are required for every table except push_tokens, which takes no dates. Same async/rate-limit behaviour as export_events: the wrapper re-polls 202 and honours Retry-After on 429. Run sequentially, start with 1-day windows and select only the fields you need. If exports keep queuing, check get_logs_api_status.

Get detailed information about a specific AppMetrica application by its ID.

Dashboard: a set of widgets computed from the public Reporting API, similar to the AppMetrica web "Обзор". The web workspaces/dashboards themselves are NOT accessible via the public API (internal cookie-auth endpoint), so dashboards are composed from presets or from a locally saved workspace (save_workspace). Presets: audience, installs, installs_by_country, engagement, app_versions, events, crashes, errors, anr, revenue, ad_revenue, ad_revenue_by_type, conversions, traffic, push, funnels, retention. Default set: audience, installs, engagement, crashes, events. See list_dashboard_presets for the metrics of each preset. Pass either widgets (preset names) or workspace (name of a locally saved workspace, which defines the widgets and may define a default app_id) — not both. With neither, the default set is used. Each widget costs one Reporting API request, run sequentially (quota: 30 requests/second, 5000/day); the 'funnels' preset costs one request per saved funnel. A failing widget returns {name, error} and does not fail the whole dashboard. Namespaces are never mixed within a request. group (day|week|month) turns widgets without breakdown into time series (no period-wide total then). segment_id (list_segments) is ANDed with each widget's own filters/segment. currency (default USD) applies to revenue widgets.

Retrieve drilldown statistics for a specific parent dimension value in AppMetrica. Useful for hierarchical data exploration.

Funnel report — the web "Funnels" report via the Reporting API: devices reaching each step in sequence, with absolute (% of step 1) and relative (% of previous step) conversion. Provide exactly one of: funnel_id (saved funnel from list_funnels — its pattern is used verbatim and the options below are ignored) or steps (ad-hoc funnel, e.g. [{"events":["app_open"]},{"events":["purchase"]}]; event names from list_events). Ad-hoc options: foreground_only (default true, count only foreground sessions), single_session (default false; true = all steps within one session), events_between_steps (default true; false = steps must follow each other directly). window_seconds limits the time from first to last step. Under the hood: ym:uf:devicesInStepN (ym:sf: for single-session) with funnel_pattern / funnel_restriction params, one request. dimensions break the funnel down (full keys or bare suffixes such as 'date', 'appVersion', 'operatingSystemInfo', 'regionCountry'); group (day|week|month) adds a time series via one extra /bytime request. filters / segment_id restrict the audience (segment expression is ANDed with filters).

Check whether the Logs API is enabled for the account ("enabled" / "disabled"). When it is disabled, export_events / export_logs keep returning 202 (queued) or 429 — this is how to find out why.

Get summary statistics for a specific push notification campaign in AppMetrica.

Retrieve aggregated statistics from AppMetrica (/stat/v1/data). Call list_metrics first (overview) or list_metrics with search/namespace to find exact keys. Quick reference: ym:u:* users · ym:s:* sessions · ym:ce:* client events · ym:cr2:* crashes · ym:i:* installs · ym:r2:* revenue · ym:pc:* push. Revenue metrics carry a literal <currency> placeholder (e.g. ym:r2:revenue<currency>) — pass currency (RUB|USD|EUR|YND) alongside. Funnel step metrics (ym:uf:*) need a funnel pattern — use get_funnel_report instead. Keep one namespace prefix per call. Known non-existent keys (4002): ym:u:sessions, ym:u:crashes, ym:u:revenue, ym:r2:revenue without <currency>. Filters use the segmentation syntax, e.g. "ym:u:operatingSystemInfo=='iOS'"; segment_id (from list_segments) ANDs a saved segment expression into filters. A sporadic 400 "Запрос слишком сложный" means: retry, narrow the date range, or pass accuracy (e.g. 0.1, sampled result).

Retrieve AppMetrica statistics as a time series (/stat/v1/data/bytime): the same metrics/dimensions as get_report, split by day/week/month/hour or a single interval (group=all). Response: data[i].metrics[m][t] arrays aligned with time_intervals, plus totals. IMPORTANT: use ONE namespace prefix per call (all metrics and dimensions ym:u:*, or all ym:s:*, ...). Mixing prefixes fails with error 4011 — issue one call per namespace. Revenue metrics with a <currency> placeholder need the currency param. segment_id (from list_segments) is ANDed with filters. A sporadic 400 "Запрос слишком сложный" means: retry, narrow the date range, or pass accuracy (e.g. 0.1).

Get a saved segment of an AppMetrica application with all fields (segment_id, api_key, name, params, expression, owner, edit_access).

Get a locally saved workspace with its full widget specs.

List all AppMetrica applications available to the authenticated user. Returns application IDs, names, platforms, and creation dates.

List conversions (attributed-event definitions) configured for an AppMetrica application: id, name, event_type, attribution_rule, status, mandatory, etc. Conversion metrics are in the ym:ae2:* namespace.

List the preset dashboard widgets usable in get_dashboard / save_workspace: name, title, namespace, metrics, breakdown dimensions, limit, whether a currency is needed, and the default set.

List the client event names reported by an AppMetrica application (Management API "events list"). Use these names as steps in get_funnel_report or as eventLabel filters.

List saved funnels of an AppMetrica application (funnel reports from the web UI): id, name, comment, decoded steps (title, events, kind), single_session, events_between_steps, grouping and the raw API pattern. Pass funnel_id to get_funnel_report to compute a saved funnel.

Catalogue of AppMetrica Reporting API metric and dimension keys, built from the official docs (scripts/update-catalog.mjs): 197 metrics, 188 dimensions. Without search/namespace returns a compact overview: namespaces table, keys verified live, known non-existent keys (traps) and recipes for analytics that need a special tool. With search (case-insensitive substring over key/name/description) and/or namespace (e.g. 'ym:u:' or 'u') returns matching entries, truncated to limit with a total count. Metrics are listed with full keys (some contain placeholders like <currency>); dimensions are listed by suffix plus the namespaces where they exist (key = namespace + suffix, e.g. ym:u: + appVersion).

List push notification campaigns (groups) for an AppMetrica application. Optionally filter by campaign status.

List saved segments of an AppMetrica application (the segments from the web UI). Returns segment_id, name, expression and edit_access. Pass segment_id to get_report / get_report_bytime / get_funnel_report / get_dashboard to restrict the report to a segment (its expression is ANDed into filters).

List locally saved workspaces (named widget sets) from /tmp/.config/appmetrica-mcp/workspaces.json (override with APPMETRICA_WORKSPACES_FILE). These are the MCP's own local workspaces — AppMetrica web workspaces are not exposed by the public API.

Create or update (upsert) a local workspace: a named set of dashboard widgets stored in /tmp/.config/appmetrica-mcp/workspaces.json. Local file operation only — nothing is written to AppMetrica, so it is not gated by APPMETRICA_ALLOW_WRITE. Each widget has a name and exactly one of: preset (audience, installs, installs_by_country, engagement, app_versions, events, crashes, errors, anr, revenue, ad_revenue, ad_revenue_by_type, conversions, traffic, push, funnels, retention), metrics (custom, single namespace; optional dimensions/filters/segment_id/limit) or funnel_id (saved funnel). Use it later via get_dashboard(workspace=name).

Update a saved funnel in AppMetrica. Requires APPMETRICA_ALLOW_WRITE=true. Only name/comment given: the saved pattern is kept verbatim. If steps or any of foreground_only / single_session / events_between_steps is given, pattern and frontend_pattern are rebuilt from the existing steps (or the new steps) merged with the given options; steps the web editor cannot represent are rejected (see create_funnel). Returns {id, name, steps, pattern, next}.

Update a saved segment in AppMetrica: fetches the segment, merges the given fields and saves it. Requires APPMETRICA_ALLOW_WRITE=true. Give name and/or events (new condition: users who did all listed client events). Omitted fields keep their saved values. Returns {segment_id, name, expression, edit_access}.

[Experimental web session] Add a section header row to an AppMetrica workspace. position is the 0-based index among the groups (default: append). Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Add one group (a row of widgets) to an existing AppMetrica workspace. A widget is exactly one of: preset (web preset id), funnel_id (saved funnel), or metrics (custom widget: namespace derived from the metric prefix, metric/dimension ids validated against the namespace). position is the 0-based index among the groups (default: append). Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Create a workspace (dashboard) in AppMetrica itself in one call. groups is an ordered list of rows; a group is {header?: string, widgets?: WidgetInput[]} (header and widgets in one group become a header row followed by a widgets row). A widget is exactly one of: preset (web preset id), funnel_id (saved funnel), or metrics (custom widget: namespace derived from the metric prefix, metric/dimension ids validated against the namespace). Limits: 20 dashboards per app, 20 widgets and 40 groups per dashboard. Returns {dashboard_id, name, url, groups}. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Delete a custom AppMetrica workspace. System dashboards (id like "<appId>/General") are refused. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Get one AppMetrica web workspace: groups with headers and widgets (dashboard_widget_id, widget_id, view kind, funnel_id), enriched with the widget name, namespace, metrics and dimensions. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex.

[Experimental web session] List report namespaces of the web constructor (id, name, Reporting API prefix, e.g. Audience = ym:u:). With namespace_id: the metrics and dimensions (id, title; first 200 each) valid for custom widgets of that namespace. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex.

[Experimental web session] List the web preset widgets usable in web_create_workspace / web_add_widgets (widget_id is the `preset` value): name, namespace, categories, metrics, dimensions, default view kind. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex.

[Experimental web session] List the app's AppMetrica web workspaces (dashboards): system ones (id "<appId>/General" = Overview, "<appId>/Audience", ...) and custom ones. Returns dashboard_id, name, is_system, preset_kind, number of groups and widgets. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex.

[Experimental web session] Create an AppMetrica workspace from a LOCAL workspace (save_workspace / list_workspaces). Each local widget becomes a header row (its name) plus a row of web widgets. Local presets map to web presets where there is a clear counterpart (audience -> AudienceMulti, installs -> Installs, engagement -> UserTimeSpent + AvgSessionTime + UserSessionsCount, app_versions -> AppVersion, crashes -> CrashFreeSessions + Crashes, errors -> ErrorLogsIos + ErrorLogsAndroid, revenue -> RevenueTotal + RevenuePurchases, ad_revenue -> AdRevenue + AdRevenueARPU + AdRevenueECPM, traffic -> Clicks + Installs + InstallConversion, push -> PushSent + PushReceived + PushOpened, retention -> RetentionDynamics, funnels -> one Funnels widget per saved funnel); the rest (installs_by_country, events, conversions, anr, ad_revenue_by_type) and local custom metrics become custom widgets; funnel_id widgets become Funnels widgets. Widgets that cannot be created (unknown metric ids, no saved funnels) are skipped and listed in "skipped". Returns {dashboard_id, name, url, groups, skipped?, notes?}. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Remove one widget from an AppMetrica workspace by dashboard_widget_id (see web_get_workspace). Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Rename an AppMetrica workspace. Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex. Requires APPMETRICA_ALLOW_WRITE=true.

[Experimental web session] Check the AppMetrica web session (Chrome profile with a Yandex login) used by the web_* tools: logged_in, Yandex login, profile directory. Starts headless Chrome on first use (about 7 seconds). Uses the unofficial AppMetrica web API through a headless Chrome session: run `npx appmetrica-mcp login` once to log in to Yandex.