Instagram Account MCP
Supports Backblaze B2 as an S3-compatible media host with short-lived presigned links for Meta to fetch publishing media and post-publish deletion.
Provides media hosting through Cloudflare quick tunnels and Cloudflare R2 S3-compatible buckets so Meta can fetch images and videos for publishing, with presigned links and cleanup after posting.
Supports Facebook Login for Business as an authentication option, allowing selection of the linked Facebook Page and use of a Page token for Instagram publishing, including resumable local video uploads.
Integrates Gemini as an AI provider for content generation, translations, and comment triage.
Publishes and schedules photos, reels, carousels, stories, and trial reels; manages comments and DMs; reads post/account insights and audience demographics; researches hashtags and competitors through Instagram's official API.
Uses Meta's official Instagram API and Meta app authentication to connect and manage Instagram professional accounts.
Supports MinIO as an S3-compatible media host with short-lived presigned links for Meta to fetch publishing media and post-publish deletion.
Integrates Ollama as a local AI provider for content generation, translations, and comment triage.
Integrates OpenAI as an AI provider for generating captions, hashtags, content ideas, translations, and comment triage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Instagram Account MCP Schedule ~/Desktop/launch.mp4 as a reel for Friday 6 pm with launch caption"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Instagram Account MCP
Run and grow an Instagram professional account from Claude, Hermes, Cursor, Codex, Windsurf or any MCP client. Publish and schedule reels, carousels, photos and stories, A/B test reels with trial reels, answer comments and DMs, read insights, find outliers and the best time to post, research hashtags and competitors, and turn long videos into reels.
“Post
~/Desktop/launch.mp4as a reel on Friday at 6 pm with a caption in my Hackyard template.” “Which of my last 30 posts got the most saves per reach, and why?” “Reply to the unanswered questions on yesterday's reel.”
It runs on your own computer, talks only to Meta's official Instagram API, and keeps your tokens in your OS keychain. No browser automation, no passwords, no third-party server.
npx @joinhackyard/instagram-account-mcp setupSetup takes about ten minutes the first time: it walks you through creating your own Meta app, picks how files reach Meta, connects your account and adds itself to the AI apps on your machine.
What it covers
Area | |
Publishing | Photos, reels, carousels (2–20 images and videos), stories and trial reels from local files or URLs. Captions, first comment, collaborators, user tags, location, alt text, cover image or frame, AI-content label. Files are converted to Instagram's specs with ffmpeg. |
Scheduling |
|
Reliability | Every post is a checkpointed job: resumable video upload (Facebook Login), container polling with backoff, re-hosting when Meta cannot fetch a file, no double publishing after a crash, per-job leases so several AI apps can share one queue. |
Engagement | Comments with replies, reply, comment, hide, delete, private replies to commenters, mentions and tags, DM conversations and replies inside the 24-hour window, AI comment triage. |
Insights | Per-post metrics (views, reach, saves, shares, watch time, skip rate, story navigation…), account metrics with breakdowns, follower and engaged-audience demographics, CSV export. |
Growth | Post diagnosis against your own baseline, outliers, best publish time from your history, hashtag research with the 7-day budget tracked, competitor benchmarks through Business Discovery, content ideas. |
A/B testing | 2–4 reel variants published as trial reels to non-followers, compared on views, reach, shares, saves, engagement or watch time with a significance test, then shared by you in the app or republished automatically. |
AI | Captions, hashtags, carousel outlines, cover critique, translations, reels cut from long videos, comment triage. Bring Claude, OpenAI, Azure OpenAI, Gemini, OpenRouter, Groq or Ollama, or let your AI app write from the brief. |
Related MCP server: Instagram MCP Server
Install
Requirements: Node.js 22.13+ and an Instagram Business or Creator account (switching is free in the Instagram app). Recommended: ffmpeg (media conversion, transcription, reels from long videos).
npx @joinhackyard/instagram-account-mcp setupSetup walks through six steps:
Your Meta app (one time). Meta only lets tools post through an app you own. Choose a login type:
Facebook Login (recommended)
Instagram Login
Needs
Instagram account linked to a Facebook Page
Just the Instagram account
Token
Page token, does not expire
60 days, refreshed automatically
Local videos
Uploaded straight to Meta (resumable)
Through the media host
Delete posts, hashtag research, competitors
✓
Not offered by Meta
Facebook Login: create an app (use case Other, type Business), add the products Instagram → API setup with Facebook login and Facebook Login for Business, add
http://localhost:8765/callbackunder Valid OAuth Redirect URIs, and copy the App ID and secret from App settings → Basic.Instagram Login: create an app with the use case Manage messaging & content on Instagram, open API setup with Instagram business login, add
http://localhost:8765/callbackas a redirect URI, copy the Instagram app ID and secret, and add your account as an Instagram Tester under App roles (accept the invite in Instagram).Your own app needs no App Review to manage accounts you own or manage (Meta's Standard Access). If Meta insists on an
httpsredirect, registerhttps://localhost:8765/callbackinstead: after signing in, the page will not load, and you paste its address back (setup andcomplete_connecthandle that).Media host. Meta downloads images (and, with Instagram Login, videos) from a public link. Pick one:
Tunnel (default, zero setup): a Cloudflare quick tunnel serves the one file being published from this computer, under a random link, only until Meta has fetched it. Setup downloads
cloudflaredfor you. This computer must be online when a post publishes.S3-compatible bucket (AWS S3, Cloudflare R2, Backblaze B2, MinIO): best for scheduling. Files get short-lived presigned links and are deleted after publishing.
Azure Blob Storage: account name and key (each file gets a read-only link), or a container SAS URL.
Connect. Your browser opens the Meta sign-in. With Facebook Login, select the Page your Instagram is linked to; every Instagram account behind the selected Pages is connected.
AI providers (optional): add Claude, OpenAI, Azure OpenAI, Gemini, OpenRouter, Groq, Ollama or a custom endpoint, and pick a model per job.
Add to your AI apps. It detects and configures Claude Desktop, Claude Code, Cursor, Windsurf, Codex and Hermes Agent, keeping your original config as
*.before-instagram-account-mcp.bak. Restart the app afterwards.Background service (recommended): publishes scheduled posts, finishes A/B tests and keeps sign-ins fresh when no AI app is open (launchd on macOS, systemd on Linux, Task Scheduler on Windows).
Prefer a global install? npm i -g @joinhackyard/instagram-account-mcp && instagram-account-mcp setup.
Manual configuration
npx @joinhackyard/instagram-account-mcp config prints snippets for your machine. The general shape:
{
"mcpServers": {
"instagram-account": {
"command": "npx",
"args": ["-y", "@joinhackyard/instagram-account-mcp@latest"]
}
}
}Hermes Agent (~/.hermes/config.yaml), where tools appear as mcp_instagram_account_*:
mcp_servers:
instagram-account:
command: "npx"
args: ["-y", "@joinhackyard/instagram-account-mcp@latest"]
timeout: 180Claude Code: claude mcp add instagram-account --scope user -- npx -y @joinhackyard/instagram-account-mcp@latest
Try it
“Check my Instagram connection.”
“Post ~/Pictures/team.jpg with a short caption about demo day and tag @the.hackyard as collaborator.”
“Turn these 8 photos in ~/Pictures/build2026 into a carousel, write the caption with my build2026 template and schedule it for Saturday 7 pm IST.”
“Make a reel from ~/Videos/talk.mp4: find the three strongest 30-second moments, cut them vertical, and show me captions before posting the best one.”
“A/B test these two hooks as trial reels for 48 hours and tell me which wins on shares.”
“How did my reels do this month compared with last month? Which three posts were outliers and why?”
“When are my followers most responsive? Plan next week's posting times.”
“List comments from the last 5 posts I haven't answered, and draft replies.”
“DM everyone who commented ‘guide’ on my last reel with the link.” (private replies, one per comment, within 7 days)
“Research #buildinpublic and #indiehackers and benchmark @someaccount against us.”
“Export insights for every post this quarter to a CSV.”
Tools
Area | Tools |
Account |
|
Publish |
|
Library |
|
Engage |
|
Insights |
|
Grow |
|
A/B testing |
|
Create |
|
Setup |
|
A/B testing with trial reels
Trial reels are shown to non-followers first, so variants do not compete in your followers' feeds. create_ab_test publishes 2–4 variants (different video, hook, caption or cover) at the same time, snapshots their insights at 6 hours, 24 hours and the decision time (default 48 hours), and compares them:
views and reach with a Poisson rate test; shares, saves and engagement as rates per reach with a two-proportion test; both one-sided with a Bonferroni correction;
a winner needs at least 90% confidence and a 5% lift, and each variant at least 100 accounts reached, otherwise the result is “inconclusive”;
average watch time can only produce a “likely winner” (Meta reports the average, not the distribution).
Meta's API cannot share a trial reel with your followers. Share the winner yourself in the Instagram app, let Instagram decide (SS_PERFORMANCE graduation), or set share_winner: "republish" to post the winning variant as a normal reel.
AI providers
Connect any mix in a terminal with npx @joinhackyard/instagram-account-mcp ai. Keys go to your OS keychain and are never sent through chat.
Provider | Writing & analysis | Vision | Images | Transcription |
Anthropic Claude | ✓ (default | ✓ | ||
OpenAI | ✓ | ✓ | ✓ ( | ✓ ( |
Azure OpenAI / AI Foundry | ✓ | ✓ | ✓ | ✓ (your deployment names) |
Google Gemini | ✓ | ✓ | ✓ | ✓ |
OpenRouter | ✓ | ✓ | ||
Groq | ✓ | ✓ ( | ||
Ollama (local) | ✓ | ✓ | ||
Other OpenAI-compatible | ✓ | ✓ | ✓ | ✓ |
Without a provider, the AI tools return the data they gathered plus a brief, and your AI app writes the result. They never publish anything themselves.
Approvals
Reading is free. Anything other people will see or that cannot be undone needs your approval: publishing and scheduling, A/B tests, replies, comments, private replies and DMs, hiding or deleting comments, turning comments off, deleting posts, and disconnecting accounts. Checks that Meta would refuse anyway (login type, the DM window, caption limits) run before you are asked.
In clients that support MCP elicitation, you get a confirm dialog.
Otherwise the tool returns
CONFIRMATION REQUIREDwith a summary and a single-use token tied to those exact arguments. If the arguments change, the token is rejected. This relies on the AI following instructions, so prefer clients with elicitation, orIG_CONFIRM=always, when the AI reads untrusted text such as comments and DMs.
Set IG_CONFIRM=always to confirm every write, or never for unattended pipelines.
Templates
Templates are JSON files in ~/.instagram-account-mcp/templates/ (or ask your AI to call save_template):
{
"name": "launch",
"description": "Product launch posts",
"caption_footer": "Link in bio.",
"hashtags": ["buildinpublic", "startup"],
"hashtags_in": "first_comment",
"mentions": ["cofounder"],
"collaborators": ["partnerbrand"],
"guidance": "First line is the outcome in under 12 words. No emoji strings."
}extends inherits another template; hashtags, mentions and collaborators are merged, and guidance is passed to your AI when it writes captions. See examples/templates.
Things Meta decides (worth knowing)
Professional accounts only. Personal accounts cannot use the API. Switching to Business or Creator is free and reversible.
Daily publishing limit. Each account can publish a fixed number of posts through the API per rolling 24 hours (Meta's docs say 50 in one place and 100 in another;
publish_budgetreads the live number). Carousels count once. Posts over the limit wait in the queue.Not possible through the API: licensed music from Instagram's library, filters, story stickers and link stickers, shopping tags, editing a caption after publishing, and graduating a trial reel. Delete, hashtag search and Business Discovery need Facebook Login.
Messaging windows. You can DM someone within 24 hours of their last message to you, and send one private reply to a comment within 7 days.
Hashtag search budget. 30 different hashtags per account per rolling 7 days.
Story insights disappear after 24 hours and are hidden below 5 viewers.
Instagram Login tokens expire after 60 days without a refresh. The server refreshes them in the background; if it was off for two months, reconnect.
Configuration
Everything works without these. Environment variables override what setup stored.
Variable | Default | |
| from keychain | Your Meta app (Instagram app ID/secret for Instagram Login) |
|
|
|
| Facebook Login for Business configuration ID (optional) | |
|
| Must match the redirect URI registered in the app |
|
| Graph API version |
|
| Data folder (state database, templates, exports, temp media) |
|
|
|
|
|
|
| S3-compatible media host | |
| Azure Blob media host | |
|
| How long hosted links stay valid at most |
| auto | Path to |
|
| Fallback when Meta's live limit cannot be read |
| auto |
|
| from keychain | AI provider keys |
| from | Azure OpenAI resource |
| from |
|
Security
Meta tokens, the app secret and storage keys are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service), or an AES-256-GCM encrypted file where there is none.
Sign-in uses a random state and a one-shot loopback server on
127.0.0.1.The tunnel host only answers for the file being published, under a random 192-bit path, and stops when idle. Bucket hosts hand Meta short-lived read-only links. Hosted files are deleted after publishing.
URL sources refuse private and internal addresses.
Logs redact tokens and signed URLs. An audit log of posts and changes is kept in the local database.
disconnect_account revoke=trueremoves the app's permissions (Facebook Login).
CLI
instagram-account-mcp setup guided setup (safe to re-run)
instagram-account-mcp connect connect or reconnect accounts
instagram-account-mcp media [kind|test] choose and test the media host (tunnel, s3, azure)
instagram-account-mcp status accounts, scheduled and recent posts
instagram-account-mcp doctor check everything, explain fixes
instagram-account-mcp install [ids|all] claude-desktop, claude-code, cursor, windsurf, codex, hermes
instagram-account-mcp uninstall [ids]
instagram-account-mcp config print config snippets
instagram-account-mcp ai connect AI providers and choose models
instagram-account-mcp service install keep scheduled posts and A/B tests running in the background
instagram-account-mcp daemon run background work in the foregroundContributing
Contributions are welcome. Start with CONTRIBUTING.md. Please follow the Code of Conduct.
Questions and setup help: Discussions, see also SUPPORT.md
Bugs and ideas: Issues
Security problems: report privately, see SECURITY.md
Release notes: CHANGELOG.md
License
MIT. Built and maintained by Hackyard. Not affiliated with, or endorsed by, Instagram or Meta. Instagram is a trademark of Meta Platforms, Inc.
Available Tools
65 toolsai_statusAI providers and modelsARead-only
Which AI providers are connected (Claude, OpenAI, Azure OpenAI, Gemini, OpenRouter, Groq, Ollama, custom) and which model each job uses: text (captions, analysis), vision (covers, images), image, transcribe. Keys are never shown.
Inputs: no named parameters.
analyze_postAnalyze a postARead-onlyIdempotent
How one post, reel or story did against your own recent posts of the same format: outlier score (views vs your median), engagement rate, saves+shares per viewer, reel watch time and skip rate, and plain-language notes. With an AI provider it adds a diagnosis and next steps; without one it returns a brief so you can write it.
Inputs: media_id (required), account, diagnose, baseline_posts.
auth_statusConnection statusARead-only
Show whether the Meta app is configured, which Instagram accounts are connected (and whether their sign-in is healthy), the default account, the login type, the media host, AI providers and Meta API usage. Call this first in a new conversation.
Inputs: no named parameters.
benchmark_competitorBenchmark another accountARead-onlyIdempotent
Public stats of any Business or Creator account (Meta's Business Discovery): followers, posting frequency, format mix, median likes/comments/views, engagement per follower, top hashtags and top posts. Compare with your own using get_account_insights. Facebook Login accounts only.
Inputs: username (required), posts, account.
best_publish_timeBest time to publishARead-onlyIdempotent
When your own posts performed best, by weekday and 3-hour block in your time zone (each post scored against your median, so one viral post does not decide), plus when followers are online if Meta provides it.
Inputs: type, posts, metric, account, +1 more.
cancel_scheduledCancel a scheduled or unfinished postADestructive
Stop a post that has not been published yet (scheduled, waiting or in progress). Hosted copies are removed. Can be undone with resume_publish. Needs the user's confirmation.
Inputs: job_id (required), confirmation_token.
caption_checkCheck a captionARead-only
Checks a caption against Instagram's limits (2,200 characters, 30 hashtags, 20 @mentions) and craft rules (hook length before "more", call to action, hashtag count, links, engagement bait), and previews it with a template applied exactly as it will be published.
Inputs: caption (required), template.
comment_on_mediaComment on a postB
Add a new top-level comment on one of your posts (e.g. a pinned-style note or first comment). Public; the user confirms first.
Inputs: message (required), media_id (required), account, confirmation_token.
complete_connectFinish a sign-in with the callback URLA
Finish a connect_account sign-in by giving the full URL the browser landed on after approving (it contains ?code=...&state=...). Use when the callback page did not load or the sign-in was done on another device.
Inputs: callback_url (required).
connect_accountConnect an Instagram accountA
Start the Meta sign-in to connect (or reconnect) Instagram professional accounts. Opens the browser on this computer and returns the sign-in link. With Facebook Login the user selects the Facebook Page(s) their Instagram account is linked to; every linked account is connected. Waits up to wait_seconds for them to finish. If the browser lands on a page that does not load, ask the user to copy that page's full address and call complete_connect with it.
Inputs: open_browser, wait_seconds.
content_ideasWhat to post nextARead-only
Next post ideas grounded in this account's recent performance: which formats and topics over- and under-performed (likes and comments vs the account's median), optionally focused on a topic. With an AI model it returns ideas with format, hook, angle, evidence and confidence; otherwise the data for you to reason from.
Inputs: count, focus, posts, account, +1 more.
create_ab_testA/B test reels with trial reelsA
Publishes 2-4 versions of a reel (different hook, cut, caption or cover) as trial reels at the same time. Instagram shows trial reels to non-followers first, so each version gets a comparable audience without spamming followers. After decide_after_hours (default 48, 12-168) the background service compares them on the chosen metric with a significance test and reports a winner or "inconclusive". Meta's API cannot graduate trial reels: you share the winner to followers in the Instagram app; with share_winner: "republish" this server instead republishes the winning version as a normal reel. Versions should differ in one thing. Each version counts toward the publishing limit. Asks the user first.
Inputs: variants (required), metric, account, template, +7 more.
critique_coverJudge and rank coversARead-only
Scores 1-4 cover images (or 4 frames taken from a video) the way people see them: full screen in the reels feed and as a small grid tile. Ranks them and lists fixes. Needs a vision model (Claude, OpenAI, Gemini, Azure).
Inputs: context (required), video_path, image_paths.
delete_commentDelete a commentADestructiveIdempotent
Permanently delete a comment on your post (yours or someone else's). Prefer hide_comment unless it must go. Cannot be undone; the user confirms first.
Inputs: comment_id (required), account, confirmation_token.
delete_mediaDelete a postADestructiveIdempotent
Permanently delete a post, reel, story or whole carousel (single carousel items cannot be deleted). Only for accounts connected with Facebook Login (Meta's rule). Cannot be undone; the user confirms first.
Inputs: media_id (required), account, confirmation_token.
delete_templateDelete a caption templateADestructive
Deletes a saved template file. Asks the user first.
Inputs: name (required), confirmation_token.
disconnect_accountDisconnect an accountADestructive
Remove a connected account from this server and delete its stored token. With revoke=true (Facebook Login) it also removes this app's permissions from the Facebook user. Scheduled posts for it stop. Needs the user's confirmation.
Inputs: revoke, account, confirmation_token.
export_insightsExport post insights to CSVAIdempotent
Writes a CSV (one row per post: date, type, link, caption, views, reach, likes, comments, saves, shares, interactions, follows, profile visits, reel watch time, skip rate) for spreadsheets. Saved in the data folder's exports/ (a bare file name goes there too). Writing anywhere else needs the user's approval. Never overwrites a file: a -1, -2... suffix is added.
Inputs: path, limit, since, until, +2 more.
find_locationFind a location IDARead-only
Instagram location tags use the Facebook Page ID of a place. Pass a Facebook Page URL or ID to check it (Facebook Login accounts), or a search query (needs Meta's Page Public Metadata Access, which most apps don't have; then look the place up on facebook.com and pass its Page URL).
Inputs: page, query, account.
find_outliersFind outlier postsBRead-onlyIdempotent
Your best and worst recent posts relative to your own median on one metric (views, reach, shares, saved, total_interactions, engagement_rate, save_share_rate, follows...). Shows what to repeat and what to drop.
Inputs: top, type, posts, metric, +1 more.
generate_captionWrite caption optionsARead-only
Drafts caption options (hook first line, short body, call to action, hashtags, and on-screen hook text for reels) from a description, a transcript file, or the media file itself (images are looked at; videos are transcribed when a transcription model is connected). Applies the template and checks Instagram's limits. Drafts only: nothing is published. Without an AI model it returns a brief so you write them.
Inputs: count, notes, format, language, +4 more.
generate_hashtagsSuggest hashtagsARead-only
Suggests a hashtag set for a post: a mix of broad, niche, community, branded and location tags with reasons, the 5-10 to actually use, and tags to avoid. AI-based; for live data on how active a hashtag is use hashtag_research (Facebook Login only, 30 hashtags per 7 days).
Inputs: topic (required), count, caption, template.
get_ab_testA/B test status and resultsARead-only
Shows an A/B test: each version's publishing status, link and latest metrics, the decision time, and (when finished) the verdict with confidence and next step. refresh: true pulls current numbers from Instagram before the decision.
Inputs: test_id (required), refresh.
get_account_insightsAccount insightsBRead-onlyIdempotent
Account-level numbers. Presets: overview (last N days totals: reach, views, accounts engaged, interactions, likes, comments, saves, shares, follows/unfollows, link taps), daily (reach per day), reach_breakdown (by reels/posts/stories and followers vs non-followers), follows (follows vs unfollows). Or set metrics yourself (reach, views, accounts_engaged, total_interactions, likes, comments, saves, shares, replies, reposts, follows_and_unfollows, profile_links_taps) with period, metric_type, breakdown and since/until (max 30 days).
Inputs: days, since, until, period, +5 more.
get_audienceAudience demographicsARead-onlyIdempotent
Who your followers (or the people who engaged) are: age, gender, country and city, with shares in %. Needs at least 100 followers; Meta returns the top 45 values per breakdown.
Inputs: top, who, account, timeframe, +1 more.
get_conversationRead a conversationBRead-onlyIdempotent
Messages in one Direct conversation, newest first (Meta returns details for the 20 most recent).
Inputs: conversation_id (required), limit, account.
get_mediaGet one postBRead-onlyIdempotent
Full details of one post, reel or carousel: caption, media and thumbnail URLs, link, counts, whether comments are on, and carousel items.
Inputs: media_id (required), account.
get_media_insightsPost insightsARead-onlyIdempotent
Lifetime numbers for posts, reels or stories: views, reach, likes, comments, saves, shares, total interactions, follows, profile visits; reels add average watch time (ms), total watch time and skip rate; stories add navigation and replies. Give media_ids, or omit them for the latest posts. Story insights vanish after 24 hours and need 5+ viewers.
Inputs: latest, account, media_ids.
get_profileAccount profileBRead-only
Live profile of a connected account: username, name, biography, website, followers, following, media count, profile picture.
Inputs: account.
get_publish_statusPublishing statusARead-only
Status of a publishing job: each item's progress (preparing, uploading %, processing), errors with fixes, and the permalink once published. Can wait for changes.
Inputs: job_id (required), wait_seconds.
hashtag_budgetHashtag search budgetARead-onlyIdempotent
How many of the 30 hashtag searches per rolling 7 days are left, and which hashtags can be repeated for free.
Inputs: account.
hashtag_researchResearch hashtagsARead-onlyIdempotent
For each hashtag: top (or most recent) public posts, their median likes and comments, format mix, related hashtags people use with it, and example posts. Instagram allows 30 different hashtags per 7 days per account (repeats are free); the remaining budget is shown. Facebook Login accounts only.
Inputs: hashtags (required), edge, limit, account.
hide_commentHide or unhide a commentAIdempotent
Hide a comment from everyone except its author (or show it again with hide: false). The user confirms first.
Inputs: comment_id (required), hide, account, confirmation_token.
list_ab_testsList A/B testsARead-only
All A/B tests, newest first, optionally filtered by status.
Inputs: status.
list_accountsList connected accountsARead-only
List the Instagram accounts connected to this server.
Inputs: no named parameters.
list_commentsList commentsARead-onlyIdempotent
Comments with their replies, for one post (media_id) or across the most recent posts. Each comment says whether you already answered. Use unanswered: true to build a reply queue; triage_comments sorts them by priority.
Inputs: posts, since, hidden, account, +3 more.
list_conversationsList Direct conversationsBRead-onlyIdempotent
Recent Instagram Direct conversations: who, their last message, and whether you can still reply (Instagram allows replies for 24 hours after their last message).
Inputs: limit, account, user_id.
list_mediaList posts and reelsARead-onlyIdempotent
The account's published posts, reels and carousels, newest first: id, type, caption (shortened), link, time, likes and comments. Use get_media for one post in full and get_media_insights for its numbers.
Inputs: type, limit, since, until, +1 more.
list_mentionsMentions and tagsARead-onlyIdempotent
Where others mention this account: posts that tagged it, newest first. With comment_id or media_id (from a mention notification) it returns that specific @mention.
Inputs: limit, account, media_id, comment_id.
list_scheduledScheduled and recent postsBRead-only
Upcoming scheduled posts (soonest first), posts being published or waiting, and recent results from this computer.
Inputs: recent, account.
list_storiesList live storiesARead-onlyIdempotent
Stories currently live (the last 24 hours). Story insights also disappear after 24 hours.
Inputs: account.
list_taggedPosts that tagged youBRead-onlyIdempotent
Media where other accounts tagged this account (photo tags), newest first.
Inputs: limit, account.
list_templatesList caption templatesBRead-only
Caption templates: header/footer, hashtags (in the caption or first comment), mentions, first comment, collaborators, location and the account voice used by the writing tools. Saved as JSON in the templates folder.
Inputs: no named parameters.
media_host_statusMedia host statusARead-only
How local files reach Instagram, and whether it works: tunnel (Cloudflare quick tunnel from this computer), s3 (S3/R2/B2 bucket) or azure (Blob Storage). Facebook-Login accounts upload videos straight to Meta; images always go through the host.
Inputs: host.
prepare_mediaCheck (and convert) media for InstagramA
Inspect an image or video and list what Instagram would reject for a placement (format, codec, aspect ratio, length, size). With convert=true, writes a fixed copy (JPEG / H.264+AAC MP4, reframed with fit) and returns its path. Publishing tools do this automatically. Needs ffmpeg.
Inputs: kind (required), file_path (required), fit, convert.
private_replyDM someone who commentedA
Send one private Direct message to the person who wrote a comment (e.g. the link they asked for). One message per comment, within 7 days of it. The user confirms first.
Inputs: message (required), comment_id (required), account, confirmation_token.
publish_budgetPublishing limitARead-only
How many API posts are left in Instagram's rolling 24-hour window (Meta's limit; carousels count once), plus posts scheduled for the next 24 hours.
Inputs: account.
publish_carouselPublish a carouselA
Publish (or schedule) a carousel of 2 to 20 images and/or videos (videos 3-60 s). Instagram crops every item to the first item's shape; use fit to control reframing. Alt text and user tags per image. Needs the user's confirmation; runs in the background.
Inputs: items (required), fit, account, caption, +9 more.
publish_photoPublish a photo postA
Publish (or schedule) a single-image feed post. Images are converted to JPEG and fitted into Instagram's 4:5 to 1.91:1 range automatically. Needs the user's confirmation. Runs in the background; follow get_publish_status.
Inputs: fit, url, account, caption, +12 more.
publish_reelPublish a reelA
Publish (or schedule) a reel: 3 seconds to 15 minutes, up to 300 MB, 9:16 fills the screen (fit: crop or blur reframes other shapes). Converted to H.264/AAC MP4 when needed. Licensed music can't be added through the API. Needs the user's confirmation; runs in the background.
Inputs: fit, url, account, caption, +16 more.
publish_storyPublish a storyA
Publish (or schedule) a story from an image or a video (3-60 s, up to 100 MB). Stories last 24 hours. Stickers, links, polls and music can't be added through the API. Needs the user's confirmation.
Inputs: fit, url, type, account, +6 more.
publish_trial_reelPublish a trial reelA
Publish a trial reel: Instagram shows it to non-followers first, so you can test an idea without your followers seeing it. graduation SS_PERFORMANCE lets Instagram share it with followers automatically if it performs well; MANUAL keeps it trial-only until you share it yourself in the Instagram app (the API has no call to graduate a trial reel). For comparing several versions, use create_ab_test. Needs confirmation.
Inputs: fit, url, account, caption, +17 more.
reply_to_commentReply to a commentA
Public reply under a top-level comment (Meta does not allow replying to replies or to hidden comments). The user confirms first.
Inputs: message (required), comment_id (required), account, confirmation_token.
repurpose_videoCut reels from a long videoA
Finds the best standalone moments in a long local video (transcribed, or from a transcript file) and cuts them into vertical 1080x1920 reels with a hook, on-screen text and caption for each. Or pass clips with start/end seconds to cut exactly those. layout crop fills the frame from the centre; blur fits the whole frame over a blurred fill. Returns file paths ready for publish_reel. Needs ffmpeg.
Inputs: file_path (required), cut, clips, count, +5 more.
rescheduleReschedule a postA
Move a scheduled, waiting or missed (computer was off) post to a new time. Needs the user's confirmation.
Inputs: job_id (required), publish_at (required), confirmation_token.
resume_publishRetry or resume a postA
Retry a failed post, continue one paused on an expired sign-in, re-check one waiting for the publishing limit, restore a cancelled one, or publish one that missed its scheduled time (computer was off) right now. Cancelled and missed posts need the user's confirmation again. If a publish may already have gone through, it checks Instagram first and never publishes twice.
Inputs: job_id (required), wait_seconds, confirmation_token.
save_templateSave a caption templateB
Creates or replaces a caption template. Use extends to build on another template (hashtags, mentions and collaborators are merged; guidance is appended).
Inputs: name (required), extends, guidance, hashtags, +9 more.
send_dmSend a Direct messageA
Reply in Instagram Direct to someone who messaged this account. Allowed only within 24 hours of their last message (7 days with human_agent if your Meta app has the Human Agent feature). Text up to 1000 bytes. The user confirms first.
Inputs: message (required), recipient_id (required), account, human_agent, +1 more.
set_ai_modelsChoose AI modelsAIdempotent
Pick which connected provider and model handle each job, as "provider:model" (Azure: "azure:"), e.g. text "anthropic:claude-opus-5-5", vision "openai:gpt-5.5", transcribe "groq:whisper-large-v3". Pass null to go back to the automatic choice.
Inputs: text, image, effort, vision, +1 more.
set_default_accountSet the default accountAIdempotent
Choose which connected account is used when a tool call does not name one.
Inputs: account (required).
stop_ab_testStop an A/B testADestructive
Stops a test: versions not yet published are cancelled and no decision is made. Trial reels already published stay up (delete them with delete_media or in the app).
Inputs: test_id (required), confirmation_token.
suggest_carouselPlan a carouselARead-only
Turns text, an article, notes or a transcript into a carousel outline: slide-by-slide headline, body and visual (up to 20 slides), plus caption and hashtags. Design the slides from it, then publish with publish_carousel.
Inputs: text, slides, audience, template, +1 more.
toggle_commentsTurn comments on or offAIdempotent
Enable or disable comments on one of your posts. Visible to everyone, so the user confirms first. (Captions cannot be edited through Meta's API.)
Inputs: enabled (required), media_id (required), account, confirmation_token.
translate_captionTranslate a captionARead-only
Drafts the caption in other languages, keeping the hook, @mentions, #hashtags and links. Drafts only.
Inputs: caption (required), languages (required).
triage_commentsSort comments and draft repliesARead-only
Reads recent comments (one post, or the latest posts) and sorts them: questions, praise, feedback, complaints, leads, spam, abuse. Each gets a priority, a suggested action (reply, private reply, hide, delete) and a draft reply, plus post ideas the audience is asking for. Drafts only: nothing is sent. Without an AI model it returns the comments for you to triage.
Inputs: posts, account, media_id, template, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 65 tools
Most tools target a clearly distinct action+resource (publishing, comment moderation, DM, scheduling, analytics), and the descriptions explicitly cross-reference when to prefer one over another (e.g. hide_comment over delete_comment, generate_hashtags vs hashtag_research). The remaining overlaps sit in clusters — get_media_insights / analyze_post / find_outliers / get_account_insights / benchmark_competitor, and list_comments / triage_comments / list_mentions — where an agent must read carefully to pick correctly.
Almost entirely snake_case, with a dominant verb_noun shape (publish_photo, reply_to_comment, get_media_insights, delete_template). A handful of noun/status names break the pattern (publish_budget, auth_status, media_host_status, hashtag_budget, ai_status, content_ideas), but the casing convention never varies, so the set stays predictable.
65 tools is far above what an agent can hold in context comfortably, even for a broad domain. Several analytics tools (get_media_insights, analyze_post, find_outliers, best_publish_time, export_insights) and AI-writing tools (generate_caption, generate_hashtags, suggest_carousel, translate_caption, content_ideas) could be consolidated behind a mode parameter.
The surface covers the full lifecycle: connect/auth, media prep, publish/schedule/cancel/resume/status, media and story listing, comments and DMs, insights and audience, competitor and hashtag research, A/B testing, AI drafting and templates. The only apparent gaps are Meta API restrictions (caption editing, sticker/music on stories), which are documented in the descriptions rather than left as dead ends.
Maintenance
Related MCP Connectors
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Instagram MCP for DM and comment automation, AI Agent and content publishing via Meta's official API
Schedule and publish social posts across 9 platforms (Instagram, LinkedIn, X, TikTok, Facebook, Threads, Pinterest, Bluesky, Mastodon) straight from Claude, ChatGPT, Cursor, or any MCP client. Create, edit, and reschedule posts, upload media, and pull account and post analytics, follower demographics, and best-time windows. 20 tools, free on every plan.
Publish and schedule Instagram posts, Reels and carousels from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes Instagram actions (posts, media, comments, DMs, insights, Messenger profile) to Claude and ChatGPT via MCP.1MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready Remote MCP Server that gives Claude direct, tool-based access to your Instagram Business account through the Meta Graph API — profile data, posts, comments, publishing, insights, analytics, hashtags, messaging, and real-time webhooks.7 npmMIT
- FlicenseNot gradedqualityDmaintenanceA production-ready MCP server for interacting with Instagram/Meta APIs, enabling AI agents to manage content, analyze performance, research competitors, and handle publishing workflows.-
- AlicenseAqualityCmaintenanceEnables AI agents such as Claude and Cursor to run an Instagram Business or Creator account through Meta's official Graph API: reading profile, post and audience insights; preparing and publishing posts, carousels, reels and stories with a confirm-before-publish step; managing comments and direct messages; and searching hashtags. It also ships with a demo mode that lets every tool work without an Instagram account or access token.17MIT