Mixpanel MCP

Instructions

Implementation Reference

• src/index.ts:1151-1198 (handler)

  The handler function that executes the tool logic by making a GET request to Mixpanel's /cohorts/list API endpoint with Basic Auth, returning the list of saved cohorts or an error.
  async function handleListSavedCohorts(args: any, config: any) { const { project_id = config.DEFAULT_PROJECT_ID } = args; try { const credentials = `${config.SERVICE_ACCOUNT_USER_NAME}:${config.SERVICE_ACCOUNT_PASSWORD}`; const encodedCredentials = Buffer.from(credentials).toString('base64'); const url = `${config.MIXPANEL_BASE_URL}/cohorts/list?project_id=${project_id}`; const options = { method: 'GET', headers: { 'accept': 'application/json', 'authorization': `Basic ${encodedCredentials}` } }; const response = await fetch(url, options); if (!response.ok) { const errorText = await response.text(); throw new Error(`HTTP error! status: ${response.status} - ${errorText}`); } const data = await response.json(); return { content: [ { type: "text", text: JSON.stringify(data) } ] }; } catch (error: unknown) { console.error("Error listing saved cohorts:", error); const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error listing saved cohorts: ${errorMessage}` } ], isError: true }; } }
• src/index.ts:498-510 (schema)

  The input schema definition for the list_saved_cohorts tool, specifying optional project_id parameter.
  { name: "list_saved_cohorts", description: "List user cohorts in the project. Useful for discovering existing user segments and getting cohort IDs for analysis.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." } } } },
• src/index.ts:632-637 (registration)

  The switch case registration in the CallToolRequestSchema handler that routes calls to list_saved_cohorts to the handleListSavedCohorts function.
  case "list_saved_funnels": return await handleListSavedFunnels(args, { SERVICE_ACCOUNT_USER_NAME, SERVICE_ACCOUNT_PASSWORD, DEFAULT_PROJECT_ID, MIXPANEL_BASE_URL }); case "list_saved_cohorts": return await handleListSavedCohorts(args, { SERVICE_ACCOUNT_USER_NAME, SERVICE_ACCOUNT_PASSWORD, DEFAULT_PROJECT_ID, MIXPANEL_BASE_URL });
• src/index.ts:232-597 (registration)

  The tool is registered in the ListToolsRequestSchema handler's tools array for tool discovery.
  return { tools: [ // Event Tools { name: "get_today_top_events", description: "Get today's top events from Mixpanel. Useful for quickly identifying the most active events happening today, spotting trends, and monitoring real-time user activity.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, type: { type: "string", enum: ["general", "average", "unique"], description: "The type of events to fetch, either general, average, or unique, defaults to general" }, limit: { type: "number", description: "Maximum number of events to return" } } } }, { name: "get_top_events", description: "Get a list of the most common events over the last 31 days. Useful for identifying key user actions, prioritizing feature development, and understanding overall platform usage patterns.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, type: { type: "string", enum: ["general", "average", "unique"], description: "The type of events to fetch, either general, average, or unique, defaults to general" }, limit: { type: "number", description: "Maximum number of events to return" } } } }, { name: "aggregate_event_counts", description: "Get event counts over time periods. Useful for analyzing event volume trends and identifying patterns in user activity over time.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, event: { type: "string", description: "The event name to get counts for" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, unit: { type: "string", enum: ["hour", "day", "week", "month"], description: "The time unit for aggregation, defaults to day" } }, required: ["event", "from_date", "to_date"] } }, { name: "aggregated_event_property_values", description: "Analyze specific event properties and their values. Useful for understanding property distributions and identifying common values.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, event: { type: "string", description: "The event name to analyze properties for" }, property: { type: "string", description: "The property name to get values for" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, limit: { type: "number", description: "Maximum number of property values to return" } }, required: ["event", "property", "from_date", "to_date"] } }, // User Profile Tools { name: "profile_event_activity", description: "Get data for a profile's event activity. Useful for understanding individual user journeys, troubleshooting user-specific issues, and analyzing behavior patterns of specific users.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, workspace_id: { type: "string", description: "The ID of the workspace if applicable" }, distinct_ids: { type: "string", description: "A JSON array as a string representing the distinct_ids to return activity feeds for. Example: [\"12a34aa567eb8d-9ab1c26f345b67-89123c45-6aeaa7-89f12af345f678\"]" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" } }, required: ["distinct_ids", "from_date", "to_date"] } }, { name: "query_profiles", description: "Query user profiles with filtering. Useful for finding users based on profile properties and analyzing user segments.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, where: { type: "string", description: "JSON string representing the filter conditions for profiles" }, select: { type: "string", description: "JSON array string of properties to return. If not specified, returns all properties" }, limit: { type: "number", description: "Maximum number of profiles to return" } } } }, // Analytics Tools { name: "query_retention_report", description: "Analyze user retention patterns. Useful for understanding how well you retain users over time and identifying cohort behavior.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, born_event: { type: "string", description: "The event that defines when users are 'born' for retention analysis" }, event: { type: "string", description: "The event to measure retention for (optional, defaults to any event)" }, born_where: { type: "string", description: "JSON string representing additional filters for the born event" }, where: { type: "string", description: "JSON string representing additional filters for the retention event" }, interval: { type: "string", enum: ["day", "week", "month"], description: "The time interval for retention analysis, defaults to day" }, interval_count: { type: "number", description: "Number of intervals to analyze, defaults to 30" } }, required: ["from_date", "to_date", "born_event"] } }, { name: "query_funnel_report", description: "Get funnel conversion data. Useful for analyzing conversion rates through multi-step user flows and identifying drop-off points.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, events: { type: "string", description: "JSON array string of events that make up the funnel steps" }, funnel_window: { type: "number", description: "Number of days users have to complete the funnel" }, interval: { type: "string", enum: ["day", "week", "month"], description: "The time interval for funnel analysis" } }, required: ["from_date", "to_date", "events"] } }, { name: "list_saved_funnels", description: "List available saved funnels in the project. Useful for discovering existing funnel analyses and getting funnel IDs for further analysis.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." } } } }, { name: "list_saved_cohorts", description: "List user cohorts in the project. Useful for discovering existing user segments and getting cohort IDs for analysis.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." } } } }, // Advanced Tools { name: "custom_jql", description: "Run custom JQL (JSON Query Language) queries. Useful for advanced analytics and custom data analysis beyond standard reports.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, script: { type: "string", description: "The JQL script to execute" } }, required: ["script"] } }, { name: "query_segmentation_report", description: "Segment events by properties. Useful for analyzing how different user segments behave and comparing event patterns across groups.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, event: { type: "string", description: "The event to segment" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, on: { type: "string", description: "The property to segment by" }, where: { type: "string", description: "JSON string representing additional filters" }, unit: { type: "string", enum: ["hour", "day", "week", "month"], description: "The time unit for segmentation, defaults to day" } }, required: ["event", "from_date", "to_date", "on"] } }, { name: "query_insights_report", description: "Get saved insights reports. Useful for accessing pre-configured analytics reports and dashboards.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, report_id: { type: "string", description: "The ID of the saved insights report to retrieve" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" } }, required: ["report_id"] } } ] };