Mixpanel MCP

Instructions

Implementation Reference

• src/index.ts:977-1044 (handler)

  The handler function that implements the core logic for the 'query_retention_report' tool. It constructs a Mixpanel API URL for retention analysis, authenticates with service account credentials, fetches the report data, and returns it as JSON or an error message.

  async function handleQueryRetentionReport(args: any, config: any) {
    const { 
      project_id = config.DEFAULT_PROJECT_ID, 
      from_date, 
      to_date, 
      born_event, 
      event, 
      born_where, 
      where, 
      interval = "day", 
      interval_count = 30 
    } = args;
    
    try {
      const credentials = `${config.SERVICE_ACCOUNT_USER_NAME}:${config.SERVICE_ACCOUNT_PASSWORD}`;
      const encodedCredentials = Buffer.from(credentials).toString('base64');
      
      let url = `${config.MIXPANEL_BASE_URL}/retention?project_id=${project_id}&from_date=${from_date}&to_date=${to_date}&born_event=${encodeURIComponent(born_event)}&interval=${interval}&interval_count=${interval_count}`;
      
      if (event) {
        url += `&event=${encodeURIComponent(event)}`;
      }
      if (born_where) {
        url += `&born_where=${encodeURIComponent(born_where)}`;
      }
      if (where) {
        url += `&where=${encodeURIComponent(where)}`;
      }
      
      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 querying retention report:", error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error querying retention report: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:406-447 (schema)

  Input schema defining parameters, types, descriptions, and required fields for the query_retention_report tool.

  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"]

• src/index.ts:403-449 (registration)

  Tool registration in the MCP tools list, including name, description, and input schema.

  {
    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"]
    }
  },

• src/index.ts:626-628 (registration)

  Dispatcher case in the main CallToolRequestHandler switch statement that routes calls to the specific handler function.

  case "query_retention_report":
    return await handleQueryRetentionReport(args, { SERVICE_ACCOUNT_USER_NAME, SERVICE_ACCOUNT_PASSWORD, DEFAULT_PROJECT_ID, MIXPANEL_BASE_URL });