Skip to main content
Glama

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.

Metricairn investigation with simulated data

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 --build

Open 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-dev

Configure 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 tools
askA

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

breakdownC
Read-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

compareB
Read-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_anomaliesB
Read-onlyIdempotent

Unusual spikes/dips (screening signals, not significance tests) in pageviews and revenue (robust historical scores).

Inputs: days. Returns: result

funnel_reportA
Read-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_investigationB
Read-onlyIdempotent

Read an immutable saved investigation and its separate human review note.

Inputs: investigation_id (required). Returns: result

get_realtimeA
Read-onlyIdempotent

Live activity: visitors, pageviews and top pages in the last 30 minutes.

Inputs: no named parameters. Returns: result

goal_reportB
Read-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_healthA
Read-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_changeA
Read-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_valuesA
Read-onlyIdempotent

Discover which values a dimension actually has (e.g. real page paths, real UTM sources).

Inputs: days, dimension. Returns: result

list_goalsA
Read-onlyIdempotent

Discover named custom-event conversion goals and their IDs.

Inputs: no named parameters. Returns: result

list_investigationsA
Read-onlyIdempotent

Recent saved evidence records, their IDs and human review status.

Inputs: no named parameters. Returns: result

list_metricsA
Read-onlyIdempotent

Catalog of available metrics and dimensions. Start here to discover what you can query.

Inputs: no named parameters. Returns: result

list_notesB
Read-onlyIdempotent

Timeline annotations: launches, deploys, campaigns the founder (or an agent) logged. Newest first.

Inputs: no named parameters. Returns: result

mcp_usageB
Read-onlyIdempotent

How AI agents are using this MCP server: tool-call counts, error rates, and recent questions.

Inputs: days. Returns: result

query_metricsC
Read-onlyIdempotent

Time series for a metric. metric: visitors|pageviews|sessions|events|revenue. interval: day|hour.

Inputs: days, metric, interval. Returns: result

retention_reportA
Read-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_attributionC
Read-onlyIdempotent

Revenue total, transactions, revenue-per-visitor, and breakdown by traffic source.

Inputs: days. Returns: result

run_queryA
Read-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

    B3.2/5.0

    Scored across 20 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to query PostHog analytics data directly via tool calls, including insights, events, feature flags, trends, and persons.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      First-party web analytics MCP server for AI agents, providing 42 tools to query traffic, events, funnels, conversions, sources, and performance data.
      40
      45 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      8
      MIT