Skip to main content
Glama
dragonkhoi

mixpanel

by dragonkhoi
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

query_retention_report

Analyze user retention and engagement over time by extracting data from Retention reports. Measure product stickiness and evaluate retention rates after specific user actions using customizable parameters.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
born_eventNoThe 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.
born_whereNoAn 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'
eventNoThe event to generate returning counts for. If not specified, looks across all events
from_dateYesThe date in yyyy-mm-dd format to begin querying from (inclusive)
intervalNoThe number of units per individual bucketed interval. Default is 1. DO NOT USE IF ALREADY PROVIDING UNIT.
interval_countNoThe number of individual buckets/intervals to return. Default is 1. DO NOT USE IF ALREADY PROVIDING UNIT.
limitNoReturn the top limit segmentation values. Only applies when 'on' is specified
onNoThe property expression to segment the second event on
project_idNoThe Mixpanel project ID. Optional since it has a default.
retention_typeNoType of retention: 'birth' (first time) or 'compounded' (recurring). Defaults to 'birth'
return_whereNoAn 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'
to_dateYesThe date in yyyy-mm-dd format to query to (inclusive)
unitNoThe 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.
workspace_idNoThe ID of the workspace if applicable

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
      };
    }
  }
);

Tool Definition Quality

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions the parameter constraint (interval/unit exclusivity), it doesn't describe important behavioral aspects: whether this is a read-only operation, potential data volume/performance implications, authentication requirements, rate limits, or what the output format looks like. For a complex 14-parameter reporting tool, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in two sentences: one stating the purpose and use cases, another providing a critical parameter constraint. Every sentence earns its place, though it could be slightly more front-loaded by leading with the parameter constraint for immediate usability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 14-parameter reporting tool with no annotations and no output schema, the description is insufficient. It doesn't explain what data format to expect, how results are structured, whether there are pagination considerations, or what authentication context is required. The description should provide more context about the tool's behavior and output expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 14 parameters thoroughly. The description adds minimal value beyond the schema - only the interval/unit exclusivity rule. It doesn't explain parameter relationships, provide examples, or clarify how parameters like 'born_event' and 'retention_type' interact in practice. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get data from your Retention reports' with specific use cases like analyzing user engagement and measuring product stickiness. It distinguishes from siblings by focusing on retention reports, but doesn't explicitly differentiate from similar reporting tools like query_frequency_report or query_funnel_report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage guidance with 'Only use params interval or unit, not both' which helps avoid parameter conflicts. However, it doesn't explain when to choose this tool over sibling reporting tools like query_funnel_report or query_insights_report, nor does it provide context about when retention analysis is appropriate versus other report types.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Related Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dragonkhoi/mixpanel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server