get_campaign_insights

Instructions

Implementation Reference

• src/tools/insights.ts:87-101 (handler)

  The 'get_campaign_insights' tool definition with its handler. The handler calls metaGet() on the campaign's /insights endpoint with campaign-level params built by insightsParams().

  export const insightsTools: ToolDef[] = [
    {
      name: "get_campaign_insights",
      description:
        "Pull performance metrics for ONE campaign. Default fields: spend, impressions, clicks, " +
        "cpc, cpm, ctr, reach, frequency, actions, conversions, purchase_roas. Default range: " +
        "last_7d. Use `breakdowns` for cuts (age, gender, country, placement). Use `time_increment=1` " +
        "for day-by-day rows.",
      inputSchema: {
        campaign_id: z.string(),
        ...SHARED_INPUT_SCHEMA,
      },
      handler: async (args) =>
        metaGet(`/${String(args.campaign_id)}/insights`, insightsParams(args, "campaign")),
    },

• src/tools/insights.ts:57-85 (schema)

  Shared input schema (SHARED_INPUT_SCHEMA) used by get_campaign_insights, defining optional fields: date_preset, time_range, breakdowns, action_breakdowns, time_increment, filtering, fields, limit, after. The tool also requires 'campaign_id'.

  const SHARED_INPUT_SCHEMA = {
    date_preset: DATE_PRESET.optional().describe("Default last_7d"),
    time_range: z
      .object({ since: z.string(), until: z.string() })
      .optional()
      .describe("{since:'YYYY-MM-DD', until:'YYYY-MM-DD'} — overrides date_preset"),
    breakdowns: z
      .array(z.string())
      .optional()
      .describe("e.g. ['age','gender'] or ['country','publisher_platform']"),
    action_breakdowns: z
      .array(z.string())
      .optional()
      .describe("e.g. ['action_type']"),
    time_increment: z
      .union([z.number().int(), z.literal("monthly"), z.literal("all_days")])
      .optional()
      .describe("1 = per-day rows, 7 = weekly, 'monthly', etc."),
    filtering: z
      .array(z.record(z.unknown()))
      .optional()
      .describe("Meta filtering spec"),
    fields: z
      .array(z.string())
      .optional()
      .describe("Override default metric list"),
    limit: z.number().int().positive().max(500).optional(),
    after: z.string().optional(),
  };

• src/tools/insights.ts:40-55 (helper)

  insightsParams() helper function that builds the query parameter bag for all insights calls, setting level, fields, date range, breakdowns, filtering, pagination.

  function insightsParams(args: Record<string, unknown>, level: string): Record<string, unknown> {
    const params: Record<string, unknown> = {
      level,
      fields: (args.fields as string[] | undefined)?.join(",") ?? DEFAULT_INSIGHTS_FIELDS,
    };
    if (args.time_range) params.time_range = args.time_range;
    else params.date_preset = args.date_preset ?? "last_7d";
  
    if (args.breakdowns) params.breakdowns = args.breakdowns;
    if (args.action_breakdowns) params.action_breakdowns = args.action_breakdowns;
    if (args.time_increment !== undefined) params.time_increment = args.time_increment;
    if (args.filtering) params.filtering = args.filtering;
    if (args.limit !== undefined) params.limit = args.limit;
    if (args.after) params.after = args.after;
    return params;
  }

• src/tools/insights.ts:31-32 (helper)

  Default insights fields string used when no custom fields are provided by the caller.

  const DEFAULT_INSIGHTS_FIELDS =
    "spend,impressions,clicks,cpc,cpm,ctr,reach,frequency,actions,conversions,cost_per_conversion,cost_per_action_type,purchase_roas,video_30_sec_watched_actions,inline_link_clicks";

• src/index.ts:47-58 (registration)

  Registration of all tools including get_campaign_insights (via insightsTools spread) into the McpServer. The server registers each tool in the loop at lines 65-89.

  const allTools: ToolDef[] = [
    ...accountTools,
    ...campaignTools,
    ...adsetTools,
    ...adTools,
    ...creativeTools,
    ...mediaTools,
    ...insightsTools,
    ...bulkTools,
    ...pageTools,
    ...adsLibraryTools,
  ];