list_campaigns

Instructions

Implementation Reference

• src/tools/campaigns.ts:6-33 (handler)

  The handler/function that executes the 'list_campaigns' tool logic. It calls the Facebook Marketing API GET /act_{accountId}/campaigns with optional filters (status, objective, fields, limit, pagination cursors) and returns the paginated response.

  // ─── list_campaigns ────────────────────────────────────────
  server.tool(
    "list_campaigns",
    "List campaigns in the ad account. Supports filtering by status and objective. Returns paginated results.",
    {
      status: z.string().optional().describe("Filter by status: ACTIVE, PAUSED, DELETED, ARCHIVED"),
      objective: z.string().optional().describe("Filter by objective: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION"),
      fields: z.string().optional().describe("Comma-separated fields to return"),
      limit: z.number().optional().default(25).describe("Number of results (default 25)"),
      after: z.string().optional().describe("Pagination cursor for next page"),
      before: z.string().optional().describe("Pagination cursor for previous page"),
    },
    async ({ status, objective, fields, limit, after, before }) => {
      try {
        const params: Record<string, unknown> = {};
        if (fields) params.fields = fields;
        if (limit) params.limit = limit;
        if (after) params.after = after;
        if (before) params.before = before;
        if (status) params.effective_status = `["${status}"]`;
        if (objective) params.objective = objective;
        const { data, rateLimit } = await client.get(`${client.accountPath}/campaigns`, params);
        return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/tools/campaigns.ts:9-17 (schema)

  Input schema for the 'list_campaigns' tool, defined using Zod. Parameters: status (optional string), objective (optional string), fields (optional string), limit (optional number, default 25), after (optional string for pagination cursor), before (optional string for pagination cursor).

  "List campaigns in the ad account. Supports filtering by status and objective. Returns paginated results.",
  {
    status: z.string().optional().describe("Filter by status: ACTIVE, PAUSED, DELETED, ARCHIVED"),
    objective: z.string().optional().describe("Filter by objective: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION"),
    fields: z.string().optional().describe("Comma-separated fields to return"),
    limit: z.number().optional().default(25).describe("Number of results (default 25)"),
    after: z.string().optional().describe("Pagination cursor for next page"),
    before: z.string().optional().describe("Pagination cursor for previous page"),
  },

• src/index.ts:49-50 (registration)

  Registration of the campaign tools (including 'list_campaigns') via the registerCampaignTools(server, client) call.

  // --- Campaign Management ---
  registerCampaignTools(server, client);

• src/tools/campaigns.ts:7-33 (registration)

  The tool is registered on the MCP server via server.tool('list_campaigns', ...) in the registerCampaignTools function.

  server.tool(
    "list_campaigns",
    "List campaigns in the ad account. Supports filtering by status and objective. Returns paginated results.",
    {
      status: z.string().optional().describe("Filter by status: ACTIVE, PAUSED, DELETED, ARCHIVED"),
      objective: z.string().optional().describe("Filter by objective: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION"),
      fields: z.string().optional().describe("Comma-separated fields to return"),
      limit: z.number().optional().default(25).describe("Number of results (default 25)"),
      after: z.string().optional().describe("Pagination cursor for next page"),
      before: z.string().optional().describe("Pagination cursor for previous page"),
    },
    async ({ status, objective, fields, limit, after, before }) => {
      try {
        const params: Record<string, unknown> = {};
        if (fields) params.fields = fields;
        if (limit) params.limit = limit;
        if (after) params.after = after;
        if (before) params.before = before;
        if (status) params.effective_status = `["${status}"]`;
        if (objective) params.objective = objective;
        const { data, rateLimit } = await client.get(`${client.accountPath}/campaigns`, params);
        return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/services/ads-client.ts:213-224 (helper)

  The accountPath getter in AdsClient returns '/act_{accountId}', used to construct the API endpoint URL for listing campaigns.

  get accountPath(): string {
    return `/act_${this.accountId}`;
  }
  
  get accountId(): string {
    if (!this.config.adAccountId) {
      throw new Error(
        "META_AD_ACCOUNT_ID is not configured. Set it as an environment variable."
      );
    }
    return this.config.adAccountId;
  }