Mixpanel MCP server setup for Claude Code and Cursor

Quick answer: The Mixpanel MCP server wraps the Mixpanel Query and Export APIs as a set of tools Claude Code or Cursor can call over stdio. Install with one npx command, drop in your project token plus service account, and the editor can run real operations against Mixpanel. Setup runs about 4 to 6 minutes end to end, tested on mcp-mixpanel on April 15, 2026.

Most teams that use Mixpanel end up copying data in and out of ChatGPT or Claude to ask questions about it. The MCP server removes that step. When you ask Claude for a summary or an action, it talks to Mixpanel itself, reads the response, and writes the answer back without the context swap. For workflows that already live in Mixpanel, that feedback loop is the whole reason to wire this up.

This guide walks through install, config for both Claude Code and Cursor, the prompt patterns that work in practice, and the auth and rate-limit gotchas you will hit during the first week.

What this server does

The server speaks MCP over stdio and forwards every tool call to the Mixpanel Query and Export APIs using project token plus service account secret for auth. It exposes roughly 8 to 12 tools, grouped into three rough buckets:

• Query event data over any date range with property filters and breakdown dimensions
• Build funnel analyses from a sequence of event names with conversion windows
• Analyze retention cohorts and compute day-N retention curves
• Get user property data for any distinct ID with the user profile API
• Export raw event streams for offline analysis (JSON Lines format)
• Check JQL (JavaScript Query Language) query results for custom aggregations

Every tool call carries the project token plus service account forward in the request headers. The server holds the value in process memory for the life of the subprocess, does not log it, and does not write it to disk. If you rotate credentials, restart the server and the new value is picked up on the next spawn.

The server does not implement a local cache. Every call is a fresh round trip to Mixpanel. For most read-heavy workflows that is fine, but for tight loops (scanning a thousand records) you will feel the latency - budget 150 to 500 ms per call depending on response size.

Installing Mixpanel MCP

The package is on npm as mcp-mixpanel. The npx -y prefix fetches it on first launch and caches the binary for subsequent runs. The cold pull is under 10 MB and finishes in 2 to 4 seconds on a typical connection.

Before touching any config, generate a project token plus service account:

1. Open https://mixpanel.com/settings/project and sign in to your Mixpanel account.
2. Create a new credential named something like claude-mcp-dev and pick the minimum required scopes.
3. Copy the value shown - it is shown only once.
4. Store the value in a shell env var so it stays out of any file you commit.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json or a per-project .mcp.json file. Add a mixpanel entry that spawns the server with MIXPANEL_PROJECT_TOKEN, MIXPANEL_SERVICE_ACCOUNT, MIXPANEL_SERVICE_ACCOUNT_SECRET in its env:

{
  "mcpServers": {
    "mixpanel": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mixpanel"
      ],
      "env": {
        "MIXPANEL_PROJECT_TOKEN": "your_token",
        "MIXPANEL_SERVICE_ACCOUNT": "your_sa",
        "MIXPANEL_SERVICE_ACCOUNT_SECRET": "your_secret"
      }
    }
  }
}

Restart Claude Code, then run /mcp in a session to confirm the Mixpanel server is attached. Call a read-only tool as a smoke test - if the response comes back with real data from your account, the project token plus service account has the right scope.

For team projects, commit a placeholder version of .mcp.json with ${MIXPANEL_PROJECT_TOKEN} inside the env value and let each developer provide the real value via their shell profile. Claude Code expands env vars when it spawns the subprocess.

Configuring for Cursor

Cursor uses the same MCP spec and reads from ~/.cursor/mcp.json. The config is identical to the Claude Code block above. Open Cursor settings, navigate to the MCP tab, and toggle the Mixpanel server on. Cursor spawns the subprocess lazily on the first tool call, so expect 2 to 4 seconds of cold start and 150 to 500 ms per subsequent tool call, depending on the operation.

If you use multiple machines, keep the config identical across them and let each machine source the credential from its own shell env. That way you never commit a real token to git.

Example prompts and workflows

A few prompts that work reliably once the server is attached:

• "Query Mixpanel for the signup_completed event count over the past 30 days, broken down by plan."
• "Build a 3-step funnel: view_pricing, start_trial, upgrade_paid, over 7 days, and tell me the conversion rate."
• "Export the last 24 hours of raw events as JSON Lines and give me a count by event name."
• "Show me day-7 retention for users who signed up in March 2026, split by acquisition source."
• "Pull the user profile for distinct ID abc-123 and show me every property and the 10 latest events."

The model will chain calls on its own. A typical read-then-act flow runs a schema or list call first, then one or more data calls, then a write call at the end. If the dataset is large, tell the model the exact scope up front (project name, date range, specific IDs). Scoping down cuts round trips from 6 or 7 calls down to 2 or 3.

One caveat: the model sometimes generates overly broad queries. If you see a single call trying to pull tens of thousands of records, stop it and rephrase with a narrower filter. Mixpanel servers tend to slow down sharply past 500 results per page.

Troubleshooting

Tool call returns 401 or auth error. The project token plus service account is wrong, expired, or has been revoked. Regenerate the credential, update your shell env, and restart the MCP server (/mcp restart mixpanel in Claude Code).

Tool call returns 403 or permission denied. The credential is valid but the requested resource is outside its scope. Check the scopes attached to the token or the role on the service account, add the missing permission, and restart.

Tool call returns 429 rate limit. Mixpanel has per-account or per-route rate limits. The server does not queue on your behalf. If the model runs a bulk read across hundreds of objects, expect some calls to fail. Ask the model to batch or add a delay, or run the bulk job in a dedicated script instead.

Server fails with ENOENT on npx. The npx binary is not on PATH in the env the editor inherits. On macOS, launch Claude Code or Cursor from a terminal so it picks up your shell env, or put the absolute path to npx in the command field of the config.

Tool call returns 422 or schema error. A field or parameter name in the request does not match what Mixpanel expects. Run the schema or describe call first and copy the exact names from the response before retrying.

Alternatives

A few options if the Mixpanel server does not fit your setup:

• Look for a dedicated server with a narrower surface if you only need one or two operations - smaller servers tend to have faster cold starts.
• Use the official Mixpanel CLI or SDK directly from a script when the task is a one-off and the MCP overhead is not worth it.
• Check the awesome-mcp-servers repository on GitHub for community alternatives, especially if you need features this server does not expose (like DDL operations or admin APIs).

For one-off exports, the Mixpanel API is straightforward to call from a script. The MCP server pays off when Claude needs to read and write in the same session without you switching to the Mixpanel UI. Good use cases include cohort analysis, funnel debugging, and product metric ad-hoc queries from inside your editor.

The Mixpanel MCP server is the right default for any workflow already rooted in Mixpanel. Four to six minutes of setup replaces hours of copy-paste between your editor and the Mixpanel dashboard. Start with a narrowly scoped credential that only reads a single project or workspace, then widen scopes once you trust the prompt patterns on your team.

Security notes

Rotate the project token plus service account on a 90-day cadence as a baseline hygiene practice. If you ever suspect a credential leaked (committed to git, pasted in a screenshot), revoke it in the Mixpanel dashboard immediately - the old value stops working within a few seconds and existing subprocesses will fail their next call.

Scope credentials to the smallest set of resources you actually need. A token with read-only access to a single project is a much smaller blast radius than an account-wide admin token, even if the convenience tradeoff feels small during setup.

Performance and cost

Most tool calls complete in 150 to 500 ms on a warm connection. Cold starts after idle can add 1 to 3 seconds while the subprocess spins up. Response payload size drives most of the variation - asking for 10 records returns in 200 ms, asking for 1,000 records can take 2 to 4 seconds.

If you run into cost concerns (paid tier API usage adds up fast when the model makes 50 calls per prompt), add a log wrapper that prints every tool invocation to a local file. Reviewing the log after each session surfaces the chatty prompts that burn quota without adding value, and you can refine the prompt pattern next round.