publish_carousel

Publish Instagram carousel posts with 2-10 images or videos using publicly accessible URLs. Add captions to share multiple photos or videos in a single post.

Instructions

Publish a carousel (album) post with 2-10 images or videos. All media must be publicly accessible URLs.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`image_urls`	Yes	List of 2-10 image/video URLs
`caption`	No	Caption for the carousel post (optional)

Implementation Reference

src/client.ts:306-343 (handler)

The `publishCarousel` method handles the logic for creating media containers for each image/video and then creating a carousel container, followed by publishing the carousel via the Instagram API.

async publishCarousel(
  imageUrls: string[],
  caption?: string
): Promise<IGPublishResult> {
  const id = this.aid();
  if (imageUrls.length < 2)
    throw new InstagramAPIError("Carousel requires at least 2 items");
  if (imageUrls.length > 10)
    throw new InstagramAPIError("Carousel supports maximum 10 items");

  const containerIds: string[] = [];
  for (const url of imageUrls) {
    const isVideo = /\.(mp4|mov)$/i.test(url);
    const body: Record<string, any> = { is_carousel_item: "true" };
    if (isVideo) {
      body.video_url = url;
      body.media_type = "VIDEO";
    } else {
      body.image_url = url;
    }
    const resp = await this.request("POST", `${id}/media`, { body });
    containerIds.push(resp.id);
  }

  const carouselBody: Record<string, any> = {
    media_type: "CAROUSEL",
    children: containerIds.join(","),
  };
  if (caption) carouselBody.caption = caption;
  const carousel = await this.request("POST", `${id}/media`, {
    body: carouselBody,
  });

  const result = await this.request("POST", `${id}/media_publish`, {
    body: { creation_id: carousel.id },
  });
  return { id: result.id };
}

src/index.ts:114-126 (registration)

The `publish_carousel` tool registration in the MCP tool definitions, including its schema (image_urls as array, caption as string).

{
  name: "publish_carousel",
  description:
    "Publish a carousel (album) post with 2-10 images or videos. All media must be publicly accessible URLs.",
  inputSchema: {
    type: "object" as const,
    properties: {
      image_urls: { type: "array", items: { type: "string", format: "uri" }, description: "List of 2-10 image/video URLs", minItems: 2, maxItems: 10 },
      caption: { type: "string", description: "Caption for the carousel post (optional)" },
    },
    required: ["image_urls"],
  },
},

src/index.ts:375-378 (handler)

The `handleTool` switch case that executes `c.publishCarousel` when the `publish_carousel` tool is called.

case "publish_carousel": {
  const result = await c.publishCarousel(args.image_urls, args.caption);
  return JSON.stringify(result, null, 2);
}

instagram-mcp