farther-ben/api-client-mixpanel

Mixpanel MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Mixpanel Analytics API. This server enables AI assistants like Claude to query analytics data, export events, and manage data schemas directly from Mixpanel.

Features

Query API Tools

• Query Insights: Analyze event trends over time with aggregated counts, unique users, or averages
• Query Funnels: Analyze conversion rates and drop-off through event sequences
• Query Retention: Measure user return rates and cohort analysis
• Query Segmentation: Break down events by property values to understand user segments

Export API Tools

• Export Events: Download raw event data with all properties for custom analysis

Lexicon API Tools

• List Schemas: Browse all event and property definitions
• Get Schema: Retrieve specific schema details
• Create Schemas: Define or update event and property metadata
• Delete Schema: Remove schema definitions

Installation

Prerequisites

• Node.js 18 or higher
• A Mixpanel account with API access
• Service Account credentials from Mixpanel

Setup

1. Clone or create the project:

   cd api-client-mixpanel
   npm install
   

2. Build the TypeScript project:

   npm run build
   

Configuration

Get Mixpanel Credentials

1. Create a Service Account:

   • Log in to Mixpanel
   • Navigate to Organization Settings → Service Accounts
   • Click Create Service Account
   • Set appropriate permissions and project access
   • Save the secret immediately (you won't be able to view it again)

2. Find your Project ID:

   • Go to Project Settings in Mixpanel
   • Copy your Project ID from the project settings page

3. Determine your data residency:

   • Check which region your Mixpanel project uses (US, EU, or India)

Environment Variables

Set the following environment variables:

export MIXPANEL_SERVICE_ACCOUNT_USERNAME="your-service-account-username"
export MIXPANEL_SERVICE_ACCOUNT_SECRET="your-service-account-secret"
export MIXPANEL_PROJECT_ID="your-project-id"
export MIXPANEL_REGION="us"  # Options: us, eu, india (default: us)

Usage with Claude Desktop

Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mixpanel": {
      "command": "node",
      "args": ["/Users/ben/code/api-client-mixpanel/dist/index.js"],
      "env": {
        "MIXPANEL_SERVICE_ACCOUNT_USERNAME": "your-service-account-username",
        "MIXPANEL_SERVICE_ACCOUNT_SECRET": "your-service-account-secret",
        "MIXPANEL_PROJECT_ID": "your-project-id",
        "MIXPANEL_REGION": "us"
      }
    }
  }
}

Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

Available Tools

query_insights

Analyze event trends over time.

Parameters:

• from_date (required): Start date in YYYY-MM-DD format
• to_date (required): End date in YYYY-MM-DD format
• event (optional): Event name to query
• type (optional): Query type (general, unique, average)
• unit (optional): Time unit (day, week, month)
• where (optional): Filter expression
• interval (optional): Number of units per interval

Example:

Show me signup trends for the last 30 days

query_funnel

Analyze conversion rates through event sequences.

Parameters:

• from_date (required): Start date in YYYY-MM-DD format
• to_date (required): End date in YYYY-MM-DD format
• funnel_id (optional): ID of saved funnel
• events (optional): Array of event names for funnel steps
• on (optional): Property to segment by
• where (optional): Filter expression
• unit (optional): Time unit (day, week, month)

Example:

What's the conversion rate from signup to first purchase in the last 7 days?

query_retention

Measure user return rates.

Parameters:

• from_date (required): Start date in YYYY-MM-DD format
• to_date (required): End date in YYYY-MM-DD format
• retention_type (optional): Type (birth, compounding)
• born_event (optional): First event defining cohort
• event (optional): Return event to measure
• unit (optional): Time unit (day, week, month)

Example:

Show me 7-day retention for users who signed up in the last month

query_segmentation

Break down events by property values.

Parameters:

• from_date (required): Start date in YYYY-MM-DD format
• to_date (required): End date in YYYY-MM-DD format
• event (required): Event name to segment
• type (optional): Aggregation type (general, unique, average)
• on (optional): Property to segment by
• where (optional): Filter expression
• limit (optional): Max number of segments

Example:

Break down page views by country for the last week

export_events

Export raw event data.

Parameters:

• from_date (required): Start date in YYYY-MM-DD format
• to_date (required): End date in YYYY-MM-DD format
• event (optional): Array of event names to filter
• where (optional): Filter expression
• limit (optional): Maximum number of events

Example:

Export all purchase events from yesterday

list_schemas

List all schemas in Lexicon.

Parameters:

• entityType (optional): Filter by type (event, property, profile_property, group_property)

Example:

Show me all event schemas

get_schema

Get details of a specific schema.

Parameters:

• entityType (required): Entity type
• name (required): Name of event or property

Example:

Get the schema for the "Purchase" event

create_schemas

Create or update schemas.

Parameters:

• entries (required): Array of schema definitions

Example:

Create a schema for a new "User Upgraded" event with description and tags

delete_schema

Delete a schema.

Parameters:

• entityType (required): Entity type
• name (required): Name of event or property

Example:

Delete the schema for the deprecated "Old Event" event

Rate Limits

The Mixpanel API has the following rate limits:

• 60 queries per hour per project
• Maximum 5 concurrent queries

This server automatically handles rate limiting by queuing requests and respecting these limits.

Development

Run in development mode:

npm run dev

Build:

npm run build

Watch mode:

npm run watch

Troubleshooting

Authentication Errors

• Verify your Service Account credentials are correct
• Ensure the Service Account has access to the project
• Check that credentials haven't expired (if you set an expiration)

Regional Errors

• Confirm your MIXPANEL_REGION matches your project's data residency
• US projects use us, EU projects use eu, India projects use india

Rate Limit Errors

• The server automatically handles rate limiting
• If you consistently hit limits, consider:
  • Reducing query frequency
  • Using broader date ranges instead of multiple narrow queries
  • Contacting Mixpanel support for increased limits

Connection Issues

• Restart Claude Desktop after configuration changes
• Check the logs in Claude Desktop's developer console
• Verify the path to dist/index.js is correct in your config

Architecture

src/
├── index.ts              # Main MCP server and tool registration
├── config.ts             # Configuration and authentication
├── mixpanel-client.ts    # HTTP client with rate limiting
├── types/
│   └── mixpanel.ts       # TypeScript type definitions
└── tools/
    ├── query.ts          # Query API tools (insights, funnels, retention, segmentation)
    ├── export.ts         # Export API tools
    └── lexicon.ts        # Lexicon API tools (schema management)

License

MIT

Resources

• Mixpanel API Documentation
• Model Context Protocol Documentation
• Claude Desktop