Skip to main content
Mixpanel Headless is an open-source SDK that exposes the full Mixpanel platform — every query engine, report type, and configuration — as a single Python object. Build agents, notebooks, scheduled scripts, or ETL pipelines that work with your product data the same way a human analyst would, without a browser.

​
Choosing between Headless and MCP

Mixpanel makes your data accessible through several interfaces:
  • Mixpanel Agent is the conversational AI inside the Mixpanel UI.
  • MCP Server connects chat assistants (Claude, ChatGPT, and others) to your data for natural-language Q&A.
  • Mixpanel Headless is the Python SDK for coding agents (Claude Code, Codex, Cursor) and for scripts, notebooks, and pipelines you write yourself.
Headless and MCP both give AI tools access to Mixpanel, but they solve different problems. Neither is strictly more capable than the other — the question is what you’re building.

​
Use MCP to plug an LLM into Mixpanel

MCP is the fastest path to an assistant that can query your data. The server is hosted, the tools are curated, and any MCP-compatible client works out of the box with no code to write. The fixed tool set is a feature. Each tool has a defined schema and a predictable result, which is what you want in a chat session where a person reads each answer and asks the next question. Choose MCP when:
  • You want natural-language Q&A inside Claude, ChatGPT, Cursor, or another assistant
  • You want conversational, interactive Q&A rather than logic composed in code
  • You value low lift and predictable behavior over customization
  • What you need is already covered by an existing tool

​
Use Headless to build on top of Mixpanel

Headless takes the opposite approach: instead of a fixed menu of tools, it gives the agent Python. That distinction matters more than it first appears. Writing code is what coding agents are best at, and code composes in ways a sequence of tool calls can’t. An agent using Headless can run several queries, join the results, apply a filter no tool parameter exposes, and loop the whole thing over every project in the org. Results come back as typed objects with a .df property, so anything you can do to a DataFrame, an agent can do to your Mixpanel data. Two capabilities follow from that:
  • Combining with other data sources. Because results are DataFrames, a script can join Mixpanel data against your warehouse, a CSV, a billing export, or a CRM pull. An assistant with several MCP servers connected can compare figures in conversation, but joining full datasets is a job for code.
  • Custom output. The agent generates the chart, report, or interface you actually want, rather than the visualizations a tool happens to return.
Headless also covers the full product surface — every report type, configuration, and asset — where MCP exposes a curated subset. Choose Headless when:
  • You’re building something custom: an agent, a pipeline, a scheduled job, or a notebook
  • The analysis is complex or multi-step enough that expressing it in code beats chaining tool calls
  • You need to combine Mixpanel data with other sources
  • You want custom visualizations or output formats
  • You need a capability outside the MCP tool set

​
Side by side

The two aren’t mutually exclusive. A common pattern is MCP for interactive exploration, then Headless for the automated workloads that come out of it.

​
Get started

Then follow the quickstart on GitHub.

​
Rate limits

The default API limit is 60 requests per hour. For production workloads or higher volume, request early access.

​
Resources