# Mixpanel

> Query Mixpanel project analytics via Service Account credentials.

Lets an agent read Mixpanel project analytics — top events, event property
breakdowns, funnels, and retention — via the Mixpanel Query API and a
**service account** credential pair.

## What it can do

| Method | What it does |
| --- | --- |
| `mixpanel_get_top_events` | List top events in a date range; sort by count, limit by N. |
| `mixpanel_get_events` | Timeseries event counts by name; supports event filters and grouping. |
| `mixpanel_get_event_names` | All event names tracked in the project, paginated. |
| `mixpanel_get_top_properties` | Top property values for a given event over a date range. |
| `mixpanel_get_event_properties` | Property breakdowns for a single event (counts per value). |
| `mixpanel_get_funnels` | List saved funnels in the project. |
| `mixpanel_get_funnel` | Conversion rates step-by-step for a saved funnel. |
| `mixpanel_get_retention` | Cohort retention table; supports daily/weekly/monthly buckets. |

## How to get credentials

Use a **Mixpanel Service Account** (project-scoped, not org-scoped) for
the Basic Auth username/secret pair, plus your numeric **Project ID**.

1. Open Mixpanel → **Project settings** (gear icon top-right) →
   **Service Accounts** tab.
2. **Create** a new service account; pick a name like
   `flymyai-mcp`. Set role to **Analyst** (read-only is enough for the
   actions above).
3. Copy the **Username** and **Secret** Mixpanel shows once on creation
   (the secret is not retrievable later — store it somewhere safe).
4. In **Project settings → Overview**, copy the **Project ID**
   (numeric).

If your project lives in the **EU** Mixpanel data residency, also set
`MIXPANEL_DATA_RESIDENCY=eu`. US is the default.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `MIXPANEL_SERVICE_ACCOUNT_USERNAME` | Service Accounts → Username |
| `MIXPANEL_SERVICE_ACCOUNT_SECRET` | Service Accounts → Secret (shown once) |
| `MIXPANEL_PROJECT_ID` | Project settings → Overview → Project ID |
| `MIXPANEL_DATA_RESIDENCY` | `us` (default) or `eu` |

## Troubleshooting

- **`401 Unauthorized`** — service account doesn't have access to that
  Project ID. Re-check the Project ID matches the project the service
  account was created in.
- **`Not Found` on EU project** — `MIXPANEL_DATA_RESIDENCY` is still
  `us`. Switch to `eu` and retry.

## Links

- [Mixpanel Service Accounts](https://docs.mixpanel.com/docs/access-security/service-accounts)
- [Mixpanel Query API reference](https://developer.mixpanel.com/reference/query-api)
