list_saved_cohorts

Retrieve all cohorts within a Mixpanel project to identify user segments, plan targeted analyses, and extract cohort IDs for filtering in reports.

Instructions

Get all cohorts in a given project. Useful for discovering user segments, planning targeted analyses, and retrieving cohort IDs for filtering in other reports.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project_id`	No	The Mixpanel project ID. Optional since it has a default.
`workspace_id`	No	The ID of the workspace if applicable

Implementation Reference

src/index.ts:627-681 (handler)

The handler function for the list_saved_cohorts tool. It constructs an authenticated GET request to the Mixpanel /api/query/cohorts/list endpoint using service account credentials, fetches the list of saved cohorts, and returns the JSON response or an error message.

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

src/index.ts:623-626 (schema)

Zod input schema for the tool, defining optional project_id and workspace_id parameters.

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

src/index.ts:621-681 (registration)

MCP server.tool registration for 'list_saved_cohorts', including name, description, input schema, and handler function.

  "list_saved_cohorts",
  "Get all cohorts in a given project. Useful for discovering user segments, planning targeted analyses, and retrieving cohort IDs for filtering in other reports.",
  {
    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"),
  },
  async ({ project_id = DEFAULT_PROJECT_ID, workspace_id }) => {
    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 || ''
      });
      
      if (workspace_id) {
        queryParams.append('workspace_id', workspace_id);
      }
      
      const url = `https://mixpanel.com/api/query/cohorts/list?${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 cohorts list:", error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error fetching Mixpanel cohorts list: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }
);

.api/apis/mixpaneldevdocs/schemas.d.ts:67-119 (schema)

JSON Schema definition for the Mixpanel /query/cohorts/list API endpoint used by the tool, including input metadata (project_id required integer, optional workspace_id) and response format (array of cohort objects with id, name, count, etc.).

declare const CohortsList: {
    readonly metadata: {
        readonly allOf: readonly [{
            readonly type: "object";
            readonly properties: {
                readonly project_id: {
                    readonly type: "integer";
                    readonly $schema: "http://json-schema.org/draft-04/schema#";
                    readonly description: "Required if using service account to authenticate request.";
                };
                readonly workspace_id: {
                    readonly type: "integer";
                    readonly $schema: "http://json-schema.org/draft-04/schema#";
                    readonly description: "The id of the workspace if applicable.";
                };
            };
            readonly required: readonly ["project_id"];
        }];
    };
    readonly response: {
        readonly "200": {
            readonly type: "array";
            readonly items: {
                readonly type: "object";
                readonly properties: {
                    readonly count: {
                        readonly type: "integer";
                    };
                    readonly is_visible: {
                        readonly type: "integer";
                        readonly description: "0 if not visible. 1 if visible";
                    };
                    readonly description: {
                        readonly type: "string";
                    };
                    readonly created: {
                        readonly type: "string";
                    };
                    readonly project_id: {
                        readonly type: "integer";
                    };
                    readonly id: {
                        readonly type: "integer";
                    };
                    readonly name: {
                        readonly type: "string";
                    };
                };
            };
            readonly $schema: "http://json-schema.org/draft-04/schema#";
        };
    };
};

mixpanel