Metadata-Version: 2.4
Name: engageable
Version: 0.5.0
Summary: Analytics MCP server for AI agents. Connects to GA4, Mixpanel, PostHog, and more.
Author-email: Brightspeed AB <per@brightspeed.se>
License: MIT
Project-URL: Homepage, https://engageable.tech
Project-URL: Repository, https://github.com/engageable-tech/engageable-mcp
Project-URL: Documentation, https://engageable.tech/docs
Keywords: analytics,mcp,ai-agent,mixpanel,posthog,ga4,amplitude,analytics-api,llm,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: anthropic>=0.80
Requires-Dist: httpx>=0.28
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.14
Requires-Dist: statsmodels>=0.14
Requires-Dist: numpy>=1.26
Requires-Dist: ruptures>=1.1
Requires-Dist: google-analytics-data>=0.18
Requires-Dist: google-auth>=2.29
Requires-Dist: google-analytics-admin>=0.22
Provides-Extra: sse
Requires-Dist: starlette; extra == "sse"
Requires-Dist: uvicorn[standard]; extra == "sse"
Dynamic: license-file

# Engageable

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

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

```bash
# 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`:

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

```bash
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 | `GA4_CREDENTIALS_JSON` + `GA4_PROPERTY_ID` |
| **Mixpanel** | Service account | `MIXPANEL_SERVICE_ACCOUNT_USERNAME` + `MIXPANEL_SERVICE_ACCOUNT_SECRET` + `MIXPANEL_PROJECT_ID` |
| **PostHog** | API key | `POSTHOG_API_KEY` + `POSTHOG_PROJECT_ID` |

You can set credentials 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 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](https://engageable.tech) handles OAuth, credential storage, scheduling, and delivery — connect your analytics with one click.

## License

MIT — see [LICENSE](LICENSE).
