mixpanel

Instructions

Implementation Reference

• src/index.ts:716-779 (handler)

  The handler function that authenticates with Mixpanel service account, builds query parameters for the retention report, fetches from https://mixpanel.com/api/query/retention, and returns the JSON data or error.
  async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, from_date, to_date, retention_type, born_event, event, born_where, return_where, interval, interval_count, unit, on, limit }) => { try { const credentials = `${SERVICE_ACCOUNT_USER_NAME}:${SERVICE_ACCOUNT_PASSWORD}`; const encodedCredentials = Buffer.from(credentials).toString('base64'); const queryParams = new URLSearchParams({ project_id: project_id || '', from_date: from_date, to_date: to_date }); if (workspace_id) queryParams.append('workspace_id', workspace_id); if (retention_type) queryParams.append('retention_type', retention_type); if (born_event) queryParams.append('born_event', born_event); if (event) queryParams.append('event', event); if (born_where) queryParams.append('born_where', born_where); if (return_where) queryParams.append('where', return_where); if (interval) queryParams.append('interval', interval.toString()); if (interval_count) queryParams.append('interval_count', interval_count.toString()); if (unit) queryParams.append('unit', unit); if (on) queryParams.append('on', on); if (limit) queryParams.append('limit', limit.toString()); const url = `https://mixpanel.com/api/query/retention?${queryParams.toString()}`; 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 fetching Mixpanel retention data:", error); const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error fetching Mixpanel retention data: ${errorMessage}` } ], isError: true }; } }
• src/index.ts:686-715 (schema)

  Zod input schema defining parameters for the retention query, including dates, events, filters, and segmentation options.
  { project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(), workspace_id: z.string().optional().describe("The ID of the workspace if applicable"), from_date: z.string().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"), to_date: z.string().describe("The date in yyyy-mm-dd format to query to (inclusive)"), retention_type: z.enum(["birth", "compounded"]).optional().describe("Type of retention: 'birth' (first time) or 'compounded' (recurring). Defaults to 'birth'"), born_event: z.string().optional().describe("The first event a user must do to be counted in a birth retention cohort, required if retention_type is 'birth'. Can use $mp_web_page_view as the born_event for general cases."), event: z.string().optional().describe("The event to generate returning counts for. If not specified, looks across all events"), born_where: z.string().optional().describe(`An expression to filter born_events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not'`), return_where: z.string().optional().describe(`An expression to filter return events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not'`), interval: z.number().optional().describe("The number of units per individual bucketed interval. Default is 1. DO NOT USE IF ALREADY PROVIDING UNIT."), interval_count: z.number().optional().describe("The number of individual buckets/intervals to return. Default is 1. DO NOT USE IF ALREADY PROVIDING UNIT."), unit: z.enum(["day", "week", "month"]).optional().describe("The interval unit: 'day' (eg use if asked for D7 or D30), 'week' (eg use if asked for W12), or 'month' (eg use if asked for M6). Default is 'day'. DO NOT USE IF ALREADY PROVIDING INTERVAL."), on: z.string().optional().describe("The property expression to segment the second event on"), limit: z.number().optional().describe("Return the top limit segmentation values. Only applies when 'on' is specified") },
• src/index.ts:683-780 (registration)

  Registration of the 'query_retention_report' MCP tool on the McpServer instance, including name, description, input schema, and handler function.
  server.tool( "query_retention_report", "Get data from your Retention reports. Useful for analyzing user engagement over time, measuring product stickiness, and understanding how well your product retains users after specific actions. Only use params interval or unit, not both.", { project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(), workspace_id: z.string().optional().describe("The ID of the workspace if applicable"), from_date: z.string().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"), to_date: z.string().describe("The date in yyyy-mm-dd format to query to (inclusive)"), retention_type: z.enum(["birth", "compounded"]).optional().describe("Type of retention: 'birth' (first time) or 'compounded' (recurring). Defaults to 'birth'"), born_event: z.string().optional().describe("The first event a user must do to be counted in a birth retention cohort, required if retention_type is 'birth'. Can use $mp_web_page_view as the born_event for general cases."), event: z.string().optional().describe("The event to generate returning counts for. If not specified, looks across all events"), born_where: z.string().optional().describe(`An expression to filter born_events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not'`), return_where: z.string().optional().describe(`An expression to filter return events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not'`), interval: z.number().optional().describe("The number of units per individual bucketed interval. Default is 1. DO NOT USE IF ALREADY PROVIDING UNIT."), interval_count: z.number().optional().describe("The number of individual buckets/intervals to return. Default is 1. DO NOT USE IF ALREADY PROVIDING UNIT."), unit: z.enum(["day", "week", "month"]).optional().describe("The interval unit: 'day' (eg use if asked for D7 or D30), 'week' (eg use if asked for W12), or 'month' (eg use if asked for M6). Default is 'day'. DO NOT USE IF ALREADY PROVIDING INTERVAL."), on: z.string().optional().describe("The property expression to segment the second event on"), limit: z.number().optional().describe("Return the top limit segmentation values. Only applies when 'on' is specified") }, async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, from_date, to_date, retention_type, born_event, event, born_where, return_where, interval, interval_count, unit, on, limit }) => { try { const credentials = `${SERVICE_ACCOUNT_USER_NAME}:${SERVICE_ACCOUNT_PASSWORD}`; const encodedCredentials = Buffer.from(credentials).toString('base64'); const queryParams = new URLSearchParams({ project_id: project_id || '', from_date: from_date, to_date: to_date }); if (workspace_id) queryParams.append('workspace_id', workspace_id); if (retention_type) queryParams.append('retention_type', retention_type); if (born_event) queryParams.append('born_event', born_event); if (event) queryParams.append('event', event); if (born_where) queryParams.append('born_where', born_where); if (return_where) queryParams.append('where', return_where); if (interval) queryParams.append('interval', interval.toString()); if (interval_count) queryParams.append('interval_count', interval_count.toString()); if (unit) queryParams.append('unit', unit); if (on) queryParams.append('on', on); if (limit) queryParams.append('limit', limit.toString()); const url = `https://mixpanel.com/api/query/retention?${queryParams.toString()}`; 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 fetching Mixpanel retention data:", error); const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error fetching Mixpanel retention data: ${errorMessage}` } ], isError: true }; } } );