How to post to Instagram from Claude Code
Instagram wants an image or video on every post, so from Claude Code the usual route is a carousel rendered from an article in your repo, or a file on disk uploaded with one shell command.
How do I post to Instagram from Claude Code?
Add the planpo.st MCP server to Claude Code, connect Instagram once in the dashboard, then ask. The first three steps are one-time.
- 1
Create an API key and add planpo.st to Claude Code
Make a scoped key in planpo.st under Settings. Run one claude mcp add command. The hosted form points at mcp.planpo.st and installs nothing. The local form runs the planpost-mcp package through npx, needs Node 18 or newer, and keeps the API key on your machine.
- 2
Confirm the server is connected
Run claude mcp list and check that planpost shows as connected.
- 3
Connect Instagram
Connect a professional Instagram account in the dashboard under Connections, either through its linked Facebook Page or with Instagram login. When it asks for permissions, leave publishing ticked or posts will fail later.
- 4
Know what the post needs
An Instagram post needs at least one image or video. Captions run to 2,200 characters. Nothing in platformSettings is required; postType picks between a feed post, a Reel and a Story.
- 5
Ask in your terminal
Say what to post and when. Claude Code finds the Instagram connection, creates the post, and tells you whether it was scheduled or kept as a draft, with the reason.
claude mcp add --transport http planpost https://mcp.planpo.st/mcp \
--header "Authorization: Bearer pk_live_xxx"claude mcp add planpost -e PLANPOST_API_KEY=pk_live_xxx -- npx -y planpost-mcpReplace pk_live_xxx with your own key.
Hosted or local for Claude Code?
For Claude Code I use the hosted one. It is a single command, there is nothing to keep updated, and a new tool on the server shows up the next time Claude Code starts. Pick local when a policy says the key must not leave the machine in a config that points at someone else's server.
- Run `claude mcp list` afterwards to confirm the server is connected.
- The local route needs Node 18 or newer.
The full walkthrough is on the Claude Code setup page.
What can Claude Code do on Instagram?
It can publish single images, carousels of up to 10 items, Reels and Stories, and invite up to 3 collaborators on image and carousel posts. It cannot publish a post without media or make a caption link clickable.
Image or carousel
1 to 10One image is a feed post, two to ten attachments are a carousel. JPEG is what Instagram accepts; PNG files are converted on the way.
Reel
postType "reel" with one video. coverImageTime picks the cover frame, in seconds.
Story
postType "story" with one image or one video.
Collab post
up to 3platformSettings.instagram.collaborators takes Instagram usernames. Works on image and carousel posts.
Instagram needs an image or video on every post, and Claude Code can take it from disk: it calls upload_media for a presigned URL, PUTs the file there with a shell command, and passes the returned asset into create_post. Files already uploaded come back from list_media, ready to reuse.
Which settings does a Instagram post take?
Instagram reads four settings. Two of them, isReel and isStory, are older flags that postType now sets for you, so in practice an agent sends postType plus the two optional ones.
| Field | Allowed values | If you leave it out | Worth knowing |
|---|---|---|---|
| postType | "post", "reel" or "story" | "post" | Takes precedence over the flags below. A vertical video, or one of 90 seconds or less, is published as a Reel even when this says "post". |
| platformSettings.instagram.isReel | true or false | Set from postType | If it disagrees with an explicit postType it is ignored and the response carries post_type_flag_ignored. |
| platformSettings.instagram.isStory | true or false | Set from postType | Same rule as isReel. Prefer postType "story". |
| platformSettings.instagram.coverImageTime | Seconds into the video | Instagram picks the frame | Reels only. 0 counts as not set. |
| platformSettings.instagram.collaborators | Up to 3 usernames, with or without @ | No collaborators | Single-image and carousel posts only. A fourth name is dropped, and the field is not sent for Reels or Stories. |
| media, platformMedia.instagram | 1 to 10 items. JPEG or PNG images, MP4 or MOV video | None, required | No media saves the post as a draft with media_required. More than 10 fails at publish. |
| platformContent.instagram | Caption, 2,200 characters or fewer | The shared content | A URL in the caption returns a link_not_clickable warning. More than 30 hashtags returns hashtags_over_limit. |
What do I type to post to Instagram from Claude Code?
Plain requests work. Each example lists the tool calls Claude Code makes in response.
1. Carousel from something you wrote
You say
Read the commits since Monday. Turn it into a 6-slide Instagram carousel in my brand kit and schedule it for Wednesday 18:00.
Tool calls
list_brand_kits()
generate_carousel({ content: "<source text>", platform: "instagram", maxSlides: 6 })
render_carousel({ slides: [...], family: "<id>", brandKitId: "<kit id>" })
get_carousel_render({ id: "<render id>" })
create_post({ content: "<caption>", media: [<6 assets>], connectionIds: ["<instagram id>"], schedule: "wednesday 18:00" })Six slides rendered server-side as images, saved to the media library and scheduled as one carousel. The render tops out at 10 slides, which is also Instagram's cap.
2. A Reel with a chosen cover
You say
The video is at ./media/demo.mp4. Schedule it as an Instagram Reel on Friday 19:00 with the cover taken 3 seconds in.
Tool calls
upload_media({ filename: "demo.mp4", contentType: "video/mp4", size: <bytes> })
PUT <file> to the returned URL (shell)
create_post({ content: "<caption>", postType: "reel", platformSettings: { instagram: { coverImageTime: 3 } }, media: [<video>], connectionIds: ["<instagram id>"], schedule: "friday 19:00" })One scheduled Reel. The video has to be MP4 or MOV; anything else is refused with the format named.
3. A collab post
You say
The image is at ./media/cover.jpg. Post it to Instagram tomorrow 11:00 as a collab with @partnerstudio, caption about the joint launch.
Tool calls
upload_media({ filename: "cover.jpg", contentType: "image/jpeg", size: <bytes> })
PUT <file> to the returned URL (shell)
create_post({ content: "<caption>", platformSettings: { instagram: { collaborators: ["partnerstudio"] } }, media: [<image>], connectionIds: ["<instagram id>"], schedule: "tomorrow 11:00" })An image post that invites the other account as a collaborator. They still have to accept the invite in Instagram before it shows on their profile.
What stops a Instagram post from Claude Code?
The tag on a card is the code that comes back in the tool result.
No media, no post
media_requiredA text-only post that targets Instagram is saved as a draft. If the same post also goes to X or LinkedIn, give Instagram its own attachments in platformMedia.instagram.
Image rules
JPEG, at least 320 pixels wide, 8 MB or smaller, aspect ratio between 4:5 and 1.91:1. PNG is converted to JPEG. GIF and WebP are refused.
10 items per carousel
Eleven attachments fail at publish with the count in the error. Trim the set before scheduling.
Short or vertical video becomes a Reel
A portrait video, or any video of 90 seconds or less, is published as a Reel whatever the post type says. Instagram does not take those as feed video.
Caption links do not work
link_not_clickableInstagram shows the URL as plain text. The create call warns about it and still schedules the post.
30 hashtags
hashtags_over_limitPast 30 the response carries a warning with the count.
Check the server before the prompt
Claude CodeIf Claude Code says it has no tool for posting, the server is not connected. claude mcp list tells you in one line, and it is faster than rephrasing the request.
Can Claude Code tell me what a Instagram post earned?
Partly. A caption link on Instagram is not clickable, so a tracked link in a caption has nothing to click and the post earns no attributed revenue from it. The clickable places are the bio link and Story link stickers, and the Instagram guide covers how those are tracked. get_revenue_overview returns totals either way, and for shops selling through Instagram the other end is usually Shopify.
Claude Code and Instagram: questions people ask
- Which image formats does it accept for Instagram?
- JPEG, and PNG which is converted to JPEG before upload. GIF and WebP are refused. Images must be at least 320 pixels wide, 8 MB or less, and between 4:5 and 1.91:1.
- Why did my video post as a Reel?
- Because it was vertical or no longer than 90 seconds. Instagram accepts those as Reels only, so the publisher routes them there.
- What happens when Claude Code sends a Instagram post that breaks a rule?
- It is told at once. The usual case on Instagram is a post with no image or video: the post is kept as a draft and the tool result carries media_required plus the fix, which Claude Code applies with update_post.
- Do I need the hosted or the local server to post to Instagram?
- Either. Both expose the same tools and both can publish to Instagram. Hosted is one command with nothing installed; local keeps the key in your own environment and needs Node 18 or newer.
- Can I run this from a script or a scheduled job?
- Yes. Claude Code runs non-interactively with a prompt as its argument, so a weekly job can ask for the Instagram posts and exit. Use a scoped API key for it and keep new posts on draft or approval until you trust the output.
Keep going
Instagram from other agents
Other networks from Claude Code