engageable 0.6.0

Analytics MCP server for AI agents. Connects to GA4, Mixpanel, PostHog, and more.

Engageable

The analytics engine for AI agents.

One MCP server that connects to Google Analytics 4, Mixpanel, PostHog, and more. 10 tools for trends, funnels, retention, anomaly detection, and natural language queries. Works with any MCP client.

Quickstart

# Recommended — no venv needed:
uvx engageable

# Or with pip:
pip install engageable
engageable-mcp

The MCP server starts on stdio. Connect it to Claude Desktop, Cursor, or any MCP client, then use the configure_source tool to connect your analytics platform interactively.

Claude Desktop

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

{
  "mcpServers": {
    "engageable": {
      "command": "uvx",
      "args": ["engageable"]
    }
  }
}

Restart Claude Desktop. You'll see 10 analytics tools available. Ask it to connect your analytics source and it will walk you through setup.

Docker

docker compose up

Connects via SSE at http://localhost:8080/sse.

Tools

Tool	What it does
get_sources	List connected data sources
configure_source	Connect a new data source interactively
website_discover	Scan a website to detect installed analytics providers
analyze_trends	Time-series analysis with trend detection, change points, anomalies
compare_segments	A/B tests, before/after, segment breakdown with statistical significance
detect_anomalies	Find spikes, drops, and unusual patterns
analyze_retention	Cohort retention curves (D1/D7/D30)
analyze_funnel	Multi-step conversion funnel with drop-off rates
analyze_cohort	Define and compare user cohorts
ask	Natural language analytics questions (routes to other tools via LLM)

Supported Data Sources

Source	Auth method	Environment variables
Google Analytics 4	Service account (recommended)	GA4_CREDENTIALS_JSON + GA4_PROPERTY_ID
Google Analytics 4	OAuth (browser sign-in)	GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET
Mixpanel	Service account	MIXPANEL_SERVICE_ACCOUNT_USERNAME + MIXPANEL_SERVICE_ACCOUNT_SECRET + MIXPANEL_PROJECT_ID
PostHog	API key	POSTHOG_API_KEY + POSTHOG_PROJECT_ID

Google Analytics 4 Setup

Service account (recommended):

1. Go to Google Cloud Console → IAM & Admin → Service Accounts
2. Create a service account and download the JSON key file
3. Enable the Google Analytics Data API
4. In GA4 → Admin → Property Access Management → add the service account email as Viewer
5. Find your Property ID in GA4 → Admin → Property Settings
6. Set environment variables:

   export GA4_CREDENTIALS_JSON=/path/to/service-account-key.json
   export GA4_PROPERTY_ID=123456789
   

OAuth (browser sign-in) — advanced:

1. Create an OAuth 2.0 Client ID (type: Desktop app) in Google Cloud Console
2. Enable the Google Analytics Data API
3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET env vars
4. Run the MCP server, then call configure_source(provider='ga4') — a browser opens for sign-in

Other Sources

Set credentials as environment variables, or use the configure_source tool to save them interactively to ~/.engageable/credentials.json. See credentials.example.json for the file format.

How It Works

Engageable exposes analytics tools via the Model Context Protocol (MCP). Any MCP-compatible client (Claude, Cursor, VS Code, custom agents) can discover and call these tools.

Each tool is a self-contained pipeline: parse the request, fetch data from the right connector, run statistical analysis, return results. The ask tool adds an LLM routing layer for natural language questions.

Responses use CSV for tabular data (50% fewer tokens than JSON) with a 1000-cell budget to keep context windows manageable.

Architecture

MCP Client (Claude, Cursor, etc.)
    │
    ▼
┌─────────────────────────────────────┐
│  MCP Server (stdio or SSE)          │
│  - Dynamic tool registration        │
│  - Credential injection             │
│  - CSV response formatting          │
├─────────────────────────────────────┤
│  Composite Skills (agent-facing)    │
│  analyze_trends, compare_segments,  │
│  detect_anomalies, analyze_funnel,  │
│  analyze_retention, analyze_cohort, │
│  ask, get_sources, configure_source │
├─────────────────────────────────────┤
│  Connector Skills (internal)        │  Analysis Skills (internal)
│  ga4_query, mixpanel_query,         │  trend_detection, significance,
│  posthog_query + metadata/probe     │  cohort_retention, forecasting,
│                                     │  bayesian_ab, correlation, ...
└─────────────────────────────────────┘

Hosted Version

Don't want to manage credentials yourself? engageable.tech handles OAuth, credential storage, scheduling, and delivery — connect your analytics with one click.

License

MIT — see LICENSE.