mixpanel

Instructions

Implementation Reference

• src/index.ts:855-932 (registration)

  Registration of the 'query_segmentation_sum' MCP tool using server.tool(), including name, description, input schema, and handler function.

    "query_segmentation_sum",
    "Sum a numeric expression for events over time. Useful for calculating revenue metrics, aggregating quantitative values, and tracking cumulative totals across different time periods.",
    {
      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"),
      event: z.string().describe("The event that you wish to get data for (single event name, not an array)"),
      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)"),
      on: z.string().describe("The expression to sum per unit time (should result in a numeric value)"),
      unit: z.enum(["hour", "day"]).optional().describe("Time bucket size: 'hour' or 'day'. Default is 'day'"),
      where: z.string().optional().describe(`An expression to filter 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'`),
    },
    async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, event, from_date, to_date, on, unit, where }) => {
      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 || '',
          event: event,
          from_date: from_date,
          to_date: to_date,
          on: on
        });
        
        if (workspace_id) queryParams.append('workspace_id', workspace_id);
        if (unit) queryParams.append('unit', unit);
        if (where) queryParams.append('where', where);
        
        const url = `https://mixpanel.com/api/query/segmentation/sum?${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 segmentation sum data:", error);
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text",
              text: `Error fetching Mixpanel segmentation sum data: ${errorMessage}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:874-931 (handler)

  The core handler logic that authenticates with Mixpanel using service account credentials, builds the query URL for the /segmentation/sum endpoint, fetches the data, and returns the JSON response or error.

  async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, event, from_date, to_date, on, unit, where }) => {
    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 || '',
        event: event,
        from_date: from_date,
        to_date: to_date,
        on: on
      });
      
      if (workspace_id) queryParams.append('workspace_id', workspace_id);
      if (unit) queryParams.append('unit', unit);
      if (where) queryParams.append('where', where);
      
      const url = `https://mixpanel.com/api/query/segmentation/sum?${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 segmentation sum data:", error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error fetching Mixpanel segmentation sum data: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:857-873 (schema)

  Zod input schema validating parameters like project_id, event, dates, 'on' expression for summing, unit, and optional where filter.

  {
    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"),
    event: z.string().describe("The event that you wish to get data for (single event name, not an array)"),
    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)"),
    on: z.string().describe("The expression to sum per unit time (should result in a numeric value)"),
    unit: z.enum(["hour", "day"]).optional().describe("Time bucket size: 'hour' or 'day'. Default is 'day'"),
    where: z.string().optional().describe(`An expression to filter 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'`),
  },