Metricairn
Metricairn's MCP server lets you explore, query, and investigate self-hosted product analytics data from an AI agent.
Discover metrics, dimensions, dimension values, goals, notes, and saved investigations.
Query time series and breakdowns for visitors, pageviews, sessions, events, and revenue.
Run funnel, revenue attribution, goal conversion, and weekly retention reports.
Compare periods, detect anomalies, view realtime activity, and check integration health.
Investigate changes with filters, coverage, timeline context, caveats, and next checks.
Execute typed analytics plans without AI or SQL, and ask natural-language questions.
Review MCP usage and read immutable saved investigations with human review notes.
All tools are read-only.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Metricairn Investigate signup changes over the last week, check coverage, and show top segments."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Metricairn
Open-source, self-hosted product analytics with an MCP server.
Track traffic, signups, and returning visitors. Investigate changes from your dashboard or AI agent, inspect query windows and collection coverage, and save reports with separate review notes.

Simulated Billwise data.
What you get
Traffic, realtime activity, custom events, ordered funnels, conversion goals, and weekly retention.
Filtered queries and change investigations with segment contributions, coverage checks, timeline context, and evidence export.
Immutable saved reports with separate review status and notes.
20 MCP tools for discovery, queries, investigations, and questions; three opt-in management tools. Structured analytics work without an AI provider.
A browser tracker with SPA navigation, bounded retries, deduplication, query cleanup, and DNT/GPC controls.
Scoped keys, credential rotation, project-data deletion, and optional alerts and digests.
Related MCP server: tech.engageable/analytics
Start
git clone https://github.com/rnepal2/metricairn.git
cd metricairn
docker compose up --buildOpen http://localhost:8000, create a project, and save the three keys shown once. The container serves the dashboard, API, and tracker; SQLite data persists in a named volume. No account, cloud service, or AI key required. For source development, see CONTRIBUTING.
Install the tracker on your site:
<script defer src="https://YOUR-HOST/static/metricairn.js"
data-api="https://YOUR-HOST/api/v1/ingest" data-key="alw_YOUR_TRACKING_KEY"></script>Track a meaningful action with window.metricairn.event('signup'), then define it as a goal in the dashboard. HTTPS and a reachable deployment are required for a real site; the local container binds to loopback. See deployment.
Connect an agent
With the API running, install the local MCP connector in the same checkout. This step requires uv and Python 3.12; uv can install Python automatically. Node and Make are not required for the Docker setup.
uv sync --locked --no-devConfigure a client that supports stdio, replacing the absolute path and project read key:
{
"mcpServers": {
"metricairn": {
"command": "/ABSOLUTE/REPO/.venv/bin/python",
"args": ["-m", "metricairn_mcp"],
"env": {
"METRICAIRN_API_URL": "http://localhost:8000",
"METRICAIRN_READ_KEY": "alr_YOUR_READ_KEY"
}
}
}
}Try: “Investigate signup changes over the last week. Check collection coverage, show the largest changed segments, and separate observations from hypotheses.”
The connector queries your running API. ask stores question history and may use an API-side AI provider if configured; tool-call telemetry is optional. MCP setup and tool reference.
Billwise example
Maya Chen, the fictional founder of an invoicing app, investigates campaign signups, conversion, and returning visitors. Follow copyable calls and results from simulated data, then replay them through a real MCP session. Walkthrough and demo setup.
Scope
Metricairn is a lightweight, self-hosted product analytics platform with an MCP server for small teams. Deployments are operator-managed, without hosted user accounts or OAuth. Cookieless tracking uses browser-local identifiers; retention measures first-observed visitors, not verified people. Production scale and recovery depend on your deployment. Metric definitions · Security.
API · Architecture · Roadmap · Product direction
MIT licensed. Contributions are welcome; see CONTRIBUTING.
Available Tools
20 toolsaskA
Answer a natural-language analytics question and store its text in project history. Common questions use a deterministic planner; a configured API-side AI provider may receive the question, schema, project identifier, and dates for validated SQL. Unsupported questions return an explicit fallback. Avoid sensitive question text. days sets the default window (1..366); recognized date phrases may override it.
Inputs: days, question. Returns: result
breakdownCRead-onlyIdempotent
Top values for a dimension: path, referrer, utm_source, utm_medium, utm_campaign, device, browser, os, country, event.
Inputs: days, limit, dimension. Returns: result
compareBRead-onlyIdempotent
Compare an equal-length previous period: traffic, custom events and revenue. Changes are descriptive. Null percent change means the previous baseline was zero.
Inputs: days. Returns: result
detect_anomaliesBRead-onlyIdempotent
Unusual spikes/dips (screening signals, not significance tests) in pageviews and revenue (robust historical scores).
Inputs: days. Returns: result
funnel_reportARead-onlyIdempotent
Conversion report for a funnel (match by name or id). Steps must be completed in order. Pass segment_by (e.g. 'device', 'utm_source') to compare conversion per segment — a visitor's segment is the dimension value on their entry-step event.
Inputs: days, funnel, segment_by. Returns: result
get_investigationBRead-onlyIdempotent
Read an immutable saved investigation and its separate human review note.
Inputs: investigation_id (required). Returns: result
get_realtimeARead-onlyIdempotent
Live activity: visitors, pageviews and top pages in the last 30 minutes.
Inputs: no named parameters. Returns: result
goal_reportBRead-onlyIdempotent
Period conversion: unique visitors with a pageview then this goal. Reports denominator, repeated occurrences and missing identity. Use date_from/date_to together for an exact window; otherwise days determines it.
Inputs: goal_id (required), days, date_to, date_from. Returns: result
integration_healthARead-onlyIdempotent
Check collection coverage and recency for pageviews, custom events, funnels, and revenue. Run this when results are empty or unexpected; missing collection limits interpretation.
Inputs: no named parameters. Returns: result
investigate_changeARead-onlyIdempotent
Investigate changes in pageviews, events, or event_count (requires event_name). Returns equal-duration comparison, additive source/device/browser/path changes, coverage, timeline notes, caveats and next checks. This describes associations, not causes. Use date_from/date_to together to fix an exact window; otherwise days determines it.
Inputs: days, metric, date_to, filters, +2 more. Returns: result
list_dimension_valuesARead-onlyIdempotent
Discover which values a dimension actually has (e.g. real page paths, real UTM sources).
Inputs: days, dimension. Returns: result
list_goalsARead-onlyIdempotent
Discover named custom-event conversion goals and their IDs.
Inputs: no named parameters. Returns: result
list_investigationsARead-onlyIdempotent
Recent saved evidence records, their IDs and human review status.
Inputs: no named parameters. Returns: result
list_metricsARead-onlyIdempotent
Catalog of available metrics and dimensions. Start here to discover what you can query.
Inputs: no named parameters. Returns: result
list_notesBRead-onlyIdempotent
Timeline annotations: launches, deploys, campaigns the founder (or an agent) logged. Newest first.
Inputs: no named parameters. Returns: result
mcp_usageBRead-onlyIdempotent
How AI agents are using this MCP server: tool-call counts, error rates, and recent questions.
Inputs: days. Returns: result
query_metricsCRead-onlyIdempotent
Time series for a metric. metric: visitors|pageviews|sessions|events|revenue. interval: day|hour.
Inputs: days, metric, interval. Returns: result
retention_reportARead-onlyIdempotent
Weekly first-observed visitor cohorts, weeks 0..12. Incomplete cells are null; identities and acquisition history affect accuracy. event_name optionally restricts returning activity, not the first-observed cohort definition. Use date_from/date_to together for an exact window; otherwise days determines it.
Inputs: days, date_to, date_from, event_name. Returns: result
revenue_attributionCRead-onlyIdempotent
Revenue total, transactions, revenue-per-visitor, and breakdown by traffic source.
Inputs: days. Returns: result
run_queryARead-onlyIdempotent
Execute a typed analytics plan without AI or SQL. Fields: metric (pageviews|visitors|sessions|events|event_count), mode (total|timeseries|breakdown), event_name (required for event_count), dimension (for breakdown), interval (day|hour), date_from/date_to (ISO UTC), limit (1..100), filters ([{field, values}]). Filter fields: path, utm_source, utm_medium, utm_campaign, device, browser, os, country, event. Filters are ANDed; values within each filter are ORed. Returns resolved plan and caveats. Example: {"metric":"event_count","event_name":"signup","mode":"breakdown","dimension":"device"}.
Inputs: plan (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Several tools overlap in querying and comparison capabilities, notably query_metrics vs run_query vs ask, and compare vs investigate_change vs detect_anomalies. Descriptions do clarify intended use, but an agent must read carefully to avoid misselection. Distinct areas like realtime, notes, health, and usage are clearer.
All names use lowercase snake_case, but the pattern is inconsistent: list_, get_, query_, run_, bare verbs like compare/ask/detect_anomalies, and noun phrases ending in _report. It remains readable but lacks a single predictable verb_noun convention.
At 20 tools, the server sits at the heavy end of the reasonable range for an analytics MCP. Many specialized reports justify their place, but the overlap among query and comparison tools suggests some consolidation is possible.
The surface broadly covers read-oriented analytics: discovery, queries, breakdowns, funnels, revenue, goals, retention, anomalies, investigations, health, realtime, and notes. Minor gaps remain, such as no tool to create/update timeline notes and no list_funnels to discover funnel names/IDs for funnel_report.
Maintenance
Related MCP Connectors
Cookieless web analytics an agent creates and queries: goals, funnels, revenue, SQL. Open source.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
AI data analyst for product analytics, billing and warehouse data. Investigations and watchers.
Privacy-first product analytics. Your agent sets up tracking and answers questions about traffic.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to query PostHog analytics data directly via tool calls, including insights, events, feature flags, trends, and persons.5MIT
- AlicenseNot gradedqualityDmaintenanceConnects to GA4, Mixpanel, PostHog and other analytics platforms, providing 9 tools for trend analysis, anomaly detection, funnel analysis, and more via natural language queries.1MIT
- AlicenseAqualityDmaintenanceFirst-party web analytics MCP server for AI agents, providing 42 tools to query traffic, events, funnels, conversions, sources, and performance data.4045 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to query a privacy-focused analytics service for aggregate stats, breakdowns, realtime visitors, and time-series trends across cloud or self-hosted deployments. It also provides connectivity checks and guided analytics playbooks.8MIT