How to post to Instagram from Cursor
Instagram from a code editor sounds odd until you remember it only needs an image. Cursor renders a carousel from the docs page you are editing and schedules it, slides capped at 10.
How do I post to Instagram from Cursor?
Add the planpo.st MCP server to Cursor, 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 Cursor
Make a scoped key in planpo.st under Settings. Add a planpost entry to mcp.json, in ~/.cursor for every project or in .cursor inside one project. The hosted entry is a URL plus an Authorization header. The local entry runs npx -y planpost-mcp with the key in env.
- 2
Confirm the server is connected
Open Cursor's MCP settings and check that planpost lists its tools.
- 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 the agent panel of the editor
Say what to post and when. Cursor finds the Instagram connection, creates the post, and tells you whether it was scheduled or kept as a draft, with the reason.
{
"mcpServers": {
"planpost": {
"url": "https://mcp.planpo.st/mcp",
"headers": { "Authorization": "Bearer pk_live_xxx" }
}
}
}{
"mcpServers": {
"planpost": {
"command": "npx",
"args": ["-y", "planpost-mcp"],
"env": { "PLANPOST_API_KEY": "pk_live_xxx" }
}
}
}Config location: Global: ~/.cursor/mcp.json · Per project: .cursor/mcp.json. Replace pk_live_xxx with your own key.
Hosted or local for Cursor?
For Cursor I would use hosted in the global config. The per project file is committed with the repo, and a key in git history is the mistake that is hard to undo. Use local when the team already runs MCP servers through npx and wants one pattern for all of them.
- A project-level .cursor/mcp.json is committed with your repo, so use the hosted form with an environment variable rather than pasting a key into it.
The full walkthrough is on the Cursor setup page.
What can Cursor 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 Cursor 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 Cursor?
Plain requests work. Each example lists the tool calls Cursor makes in response.
1. Carousel from something you wrote
You say
Look at the diff on this branch. 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 recording is in this workspace at assets/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 screenshot is in this workspace at assets/feature.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 Cursor?
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.
The project config gets committed
CursorA .cursor/mcp.json inside the repo travels with it. Put the planpo.st key in the global file or an environment variable, not in a file your teammates and your git history will keep.
Can Cursor 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.
Cursor 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 Cursor 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 Cursor applies with update_post.
- Should the config be global or per project?
- Global if you post about everything you build, per project if only one repo should reach your Instagram account. The per project file is committed with the code, so keep the key out of it.
- Does this work in agent mode only?
- MCP tools are called by Cursor's agent, so yes, ask in agent mode. The Instagram tools then sit next to the editor's own file and terminal tools.
Keep going
Instagram from other agents
Other networks from Cursor