# Engageable

**The open source analytics engine for AI agents.**

One MCP server that connects to GA4, Mixpanel, PostHog, and more. 9 tools that replace per-platform integrations. Bring your own Anthropic key.

## Quickstart

```bash
pip install engageable
export ANTHROPIC_API_KEY=sk-ant-...
export POSTHOG_API_KEY=phc_...
export POSTHOG_PROJECT_ID=12345
engageable-mcp
```

That's it. The MCP server is running on stdio. Connect it to Claude Desktop, Cursor, or any MCP client.

## Claude Desktop

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

```json
{
  "mcpServers": {
    "engageable": {
      "command": "engageable-mcp",
      "args": []
    }
  }
}
```

Restart Claude Desktop. You'll see 9 analytics tools available.

## Docker

```bash
ANTHROPIC_API_KEY=sk-ant-... docker compose -f docker-compose.mcp.yml 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 (saves to `~/.engageable/credentials.json`) |
| `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 | What you need |
|--------|------|--------------|
| **PostHog** | API key | `POSTHOG_API_KEY` + `POSTHOG_PROJECT_ID` |
| **Mixpanel** | Service account | `MIXPANEL_SERVICE_ACCOUNT_USERNAME` + `MIXPANEL_SERVICE_ACCOUNT_SECRET` + `MIXPANEL_PROJECT_ID` |
| **Google Analytics 4** | Service account | `GA4_CREDENTIALS_JSON` (path or inline) + `GA4_PROPERTY_ID` |

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

## How It Works

Engageable exposes analytics tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). 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 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, posthog_query,          │  trend_detection, significance,
│  mixpanel_query, + metadata/probe   │  cohort_retention, forecasting,
│                                     │  bayesian_ab, correlation, ...
└─────────────────────────────────────┘
```

## License

MIT
<!-- mcp-name: tech.engageable/analytics -->