Instagram Campaign MCP
Provides tools for running organic Instagram campaigns through the official Instagram Graph API: publishing images, carousels, Reels, trial Reels and Stories; scheduling posts; moderating comments; collecting insights; researching hashtags and competitors; and identifying winning posts and A/B variants.
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 Campaign MCP schedule a Reel for tomorrow at 6pm tagged campaign spring_sale"
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 Campaign MCP
An MCP server that lets Claude (or any MCP client) run organic Instagram campaigns on the official Instagram Graph API: publish, schedule, moderate, measure, and find the posts that beat your own average — the ones worth turning into ads.
Fork of jlbadano/ig-mcp (MIT), rebuilt for Graph API v25 and MCP SDK 2.x.
What it adds over upstream
Area | Upstream | This fork |
Publishing | single image/video (video broke: no processing wait) | image, carousel (2–10), Reels, trial Reels, Stories, with container polling |
Scheduling | – | local queue + scheduler ( |
Insights | v19 metrics incl. deprecated ones | per-type metrics (feed / Reels / Stories), auto-fallback when Meta rejects one |
Comments | – | list, reply, comment, hide/unhide, delete |
Research | – | hashtag top/recent posts, competitor stats (Business Discovery) |
Winners | – | daily insight snapshots, scoring vs your account's median, A/B variant comparison |
Auth | token in URL query |
|
Related MCP server: Instagram MCP Server
The campaign loop
plan ─► publish / schedule_post (tag campaign + variant + hypothesis)
│
▼
collect_insights (daily) ─► rank_posts ─► winners = ad candidates
│ │
└──── compare_variants ◄──┘ (which hook / format / CTA wins)Trial Reels (
trial_graduation) show a Reel to non-followers first — a clean way to test hooks without spamming followers.SS_PERFORMANCElets Instagram share it to followers if it performs;MANUALleaves that to you in the app.A post is judged after 48h, only against posts of the same type, read at a similar age (a 2-day-old post isn't compared with posts measured at 30 days), and needs a minimum reach (default 300) before it can be called a winner.
Stories are judged on a snapshot taken 20–24h after posting (they expire at 24h). The scheduler daemon snapshots live Stories every hour; without it, run
ig-campaign collect --stories-onlyhourly. A Story that expired without such a snapshot is reported asincomplete.engagement_index= weighted average of per-reach rates divided by your median: follows ×4, shares ×3, saves ×3, profile visits ×2, comments ×1.5, likes ×0.5, Reels avg watch time ×2.1.0= typical post.Winner = enough reach and either engagement ≥ 1.5× (
WINNER_THRESHOLD) or reach ≥ 2× the median with at least median engagement (a post that travelled far without diluting engagement).
Setup
1. Meta prerequisites
Instagram Business or Creator account linked to a Facebook Page.
A Meta developer app with the Instagram Graph API.
A long-lived user token (60 days) with:
instagram_basic,instagram_content_publish,instagram_manage_insights,instagram_manage_comments,pages_show_list,pages_read_engagement,business_management. As the app's admin you can use these on your own account without App Review. See AUTHENTICATION_GUIDE.md.Hashtag search needs the Instagram Public Content Access feature on the app.
2. Install (one command)
git clone https://github.com/enimarix/instagram-campaign-mcp.git
cd instagram-campaign-mcpWindows (PowerShell):
powershell -ExecutionPolicy Bypass -File .\install.ps1 -RegisterClaudeCodemacOS / Linux:
./install.sh --register-claude-codeThe installer:
creates
.venvwith Python 3.12 using uv if it is installed (uv downloads Python itself, so a new machine only needs uv), otherwise with any installed Python 3.10+;installs the package, and creates
.envfromenv.example(never overwrites it);writes
mcp-config.jsonwith this machine's paths, ready to paste into Claude Desktop;with
-RegisterClaudeCode/--register-claude-code, runsclaude mcp add(user scope) so Claude Code sees the server right away.
Options: -Dev / --dev also installs test dependencies and runs the 67 tests
(no network); -Name / --name changes the server name (default instagram).
Re-running the installer is safe and upgrades the install.
Then fill in INSTAGRAM_ACCESS_TOKEN and INSTAGRAM_BUSINESS_ACCOUNT_ID in .env.
Don't know your account ID? Set only the token, connect the server, and call
get_account_pages.
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp env.example .env
pytest -q3. Connect to Claude
Claude Code: use --register-claude-code above, or run the claude mcp add
command the installer prints.
Claude Desktop: merge the generated mcp-config.json into
claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS:
~/Library/Application Support/Claude/), then restart Claude Desktop. It looks like:
{
"mcpServers": {
"instagram": {
"command": "/path/to/instagram-campaign-mcp/.venv/bin/ig-campaign-mcp"
}
}
}The .env in the project folder is found automatically.
4. Run the scheduler (if you schedule posts or measure Stories)
The Graph API publishes immediately — it has no "post at 18:00". Keep this running
on a machine that's on at posting time (it also snapshots live Stories hourly;
--stories-every 0 turns that off):
.venv/bin/ig-campaign worker # Windows: .venv\Scripts\ig-campaign.exe worker
# or, with the venv activated:
ig-campaign worker # checks every 60s (`daemon` is the old name, still works)
# or from cron / Task Scheduler every 5 min:
ig-campaign run-dueA post more than MAX_LATE_MINUTES (default 30) late, for example because the PC was
asleep, is moved to the next free slot instead of being published late, and two posts
never go out closer than MIN_SLOT_GAP_MINUTES. PUBLISHING_PAUSED=true holds the whole
queue; the website's pause switch (POST /api/worker/pause / resume) overrides it.
On Windows the worker registers one Task Scheduler task, IGCampaignWake, that wakes
the PC 5 minutes before the next queued post. Windows only honours it when wake timers
are allowed: Control Panel → Power Options → Change plan settings → Change advanced
power settings → Sleep → Allow wake timers → Enable (on battery too, for a laptop).
Also run ig-campaign collect once a day (or ask Claude to call collect_insights).
If a publish fails because the daily quota is reached, the post waits an hour and
tries again without using up its retries. If Instagram might have published it
anyway (timeout, or an error while the post shows as published), it is marked
failed for you to check instead of risking a double post.
5. Run the studio (website + API + scheduler)
Needs Node 22.12+ once, to build the website:
npm --prefix web ci && npm --prefix web run build # again after each website update
ig-campaign up # API, website and the daemon aboveOpen http://127.0.0.1:8765. Ctrl+C stops everything. Without an Instagram token it
starts in setup mode: the website works, publishing idles until the token is in .env.
To review from your phone, set UI_PASSWORD in .env, then
ig-campaign up --host 0.0.0.0 and open http://<pc-ip>:8765. Without a password
the studio only answers on 127.0.0.1 / localhost. Plain http:// on Wi-Fi is enough
to watch and approve; recording on the phone needs HTTPS (Tailscale serve or a
tunnel, gate H7).
Tools (30)
Account validate_access_token, get_account_pages, get_profile_info,
get_account_insights, get_publishing_limit
Content get_media_posts, get_media_insights
Publish now publish_image, publish_carousel, publish_reel, publish_story
Schedule schedule_post, list_scheduled_posts, reschedule_post,
cancel_scheduled_post, run_due_posts
Comments get_comments, reply_to_comment, comment_on_media, hide_comment,
delete_comment
Research search_hashtag, get_competitor_profile
Winners & A/B collect_insights, rank_posts, compare_variants, label_post
DMs (needs instagram_manage_messages, see INSTAGRAM_DM_SETUP.md)
get_conversations, get_conversation_messages, send_dm
Tool profiles
IG_MCP_PROFILE picks which tools the server registers (an unknown value stops it):
full(default): all 30 tools, for the owner's interactive sessions.agent: only a read-only allow-list (AGENT_TOOLSinsrc/instagram_mcp_server.py) for unattended runs; the agent runner (step 058) uses it. Nothing that publishes, schedules, comments, hides, deletes, relabels, sends or reads DMs is registered, so it can neither be listed nor called. New tools stay out until added on purpose.
Limits to know
Media must be at a public HTTPS URL; Instagram downloads it.
Images must be JPEG (the publishing API rejects PNG). Feed images: any ratio from 4:5 to 1.91:1. Reels: MP4/MOV H.264 + AAC, 9:16 recommended. Carousels crop every slide to the first slide's ratio. These checks run before anything is sent to Meta (
VALIDATE_IMAGE_RATIO=falseskips them).~100 API-published posts per rolling 24h (
get_publishing_limitshows usage).Stories via API: no stickers, links or text overlays — bake them into the media.
30 unique hashtag searches per 7 days.
Client-side cap of 200 API calls/hour (
RATE_LIMIT_REQUESTS_PER_HOUR): when it is reached, calls fail at once with "next slot in N min" instead of hanging.Tokens expire after 60 days; regenerate before then.
Insights count organic interactions only; ad interactions are excluded.
Configuration
See env.example. Most useful: TIMEZONE (default Europe/Paris, used
for schedule times without an offset), WINNER_MIN_AGE_HOURS, WINNER_MIN_REACH,
WINNER_THRESHOLD, DATABASE_PATH, MEDIA_ROOT (asset files, served at /api/media;
ig-campaign dev seed --db x.db puts them in media/ next to x.db, so point MEDIA_ROOT
there too if you open that seed in the website).
.env and the database live in the project folder for a clone or the installer's
editable install. With a plain pip install . they go to ~/.instagram-campaign-mcp
instead (the code then sits in site-packages). IG_MCP_HOME overrides both.
Roadmap
Paid side: promote winning posts as ads (existing post as creative), A/B tests, budget caps enforced in code.
Resumable upload for local video files (no public URL needed).
License
MIT — original work © José Luis Badano; campaign extensions © Amine El Kerzazi.
Available Tools
30 toolscancel_scheduled_postA
Cancel a pending or failed scheduled post (a pending studio asset goes back to approved).
Inputs: post_id (required). Returns: result
collect_insightsA
Snapshot insights of recent posts (and live Stories) into the local store. Run daily; scoring uses the latest snapshot of each post. Stories are only judged on a snapshot taken 20-24h after posting: the scheduler daemon takes those hourly, or call this with stories_only=True.
Inputs: limit, max_age_days, stories_only. Returns: result
comment_on_mediaA
Add a comment from the account on one of its own posts (e.g. a pinned CTA).
Inputs: message (required), media_id (required). Returns: result
compare_variantsARead-only
Compare A/B variants inside a campaign (by the variant labels given at publish/schedule time). Says when the gap is too small or the sample too thin.
Inputs: campaign (required). Returns: result
delete_commentADestructive
Permanently delete a comment. Prefer hide_comment unless the user asked.
Inputs: comment_id (required). Returns: result
get_account_insightsBRead-only
Account-level insights. Default metrics: reach, views, accounts_engaged, total_interactions. Others: likes, comments, saves, shares, replies, follows_and_unfollows, profile_links_taps. since/until: ISO dates (max 30 days).
Inputs: since, until, period, metrics, +1 more. Returns: result
get_account_pagesARead-only
List Facebook Pages for this token and their linked Instagram account IDs (use the id as INSTAGRAM_BUSINESS_ACCOUNT_ID).
Inputs: no named parameters. Returns: result
get_commentsBRead-only
Top-level comments on a post (with first-level replies).
Inputs: media_id (required), limit. Returns: result
get_competitor_profileBRead-only
Public stats and recent posts (likes, comments, captions) of another Business/Creator account, for benchmarking.
Inputs: username (required), media_limit. Returns: result
get_conversation_messagesCRead-only
Messages in one DM conversation.
Inputs: conversation_id (required), limit, page_id. Returns: result
get_conversationsBRead-only
Instagram DM conversations (needs instagram_manage_messages). page_id defaults to the Facebook Page linked to the configured Instagram account.
Inputs: limit, page_id. Returns: result
get_media_insightsARead-only
Insights for one post. Metrics are picked automatically for feed posts, Reels or Stories unless given.
Inputs: media_id (required), metrics. Returns: result
get_media_postsBRead-only
Recent posts (newest first) with type, caption, permalink, likes, comments.
Pass next_cursor as after for the next page.
Inputs: after, limit. Returns: result
get_profile_infoBRead-only
Profile of the configured account: username, bio, followers, post count.
Inputs: account_id. Returns: result
get_publishing_limitARead-only
How many API posts were published in the last 24h vs the quota.
Inputs: no named parameters. Returns: result
hide_commentAIdempotent
Hide (or unhide) a comment. Reversible, unlike delete.
Inputs: comment_id (required), hide. Returns: result
label_postA
Attach campaign/variant/hypothesis to an existing post (e.g. one published from the app) so it counts in compare_variants.
Inputs: media_id (required), variant, campaign, hypothesis. Returns: result
list_scheduled_postsBRead-only
Show the publishing queue, optionally filtered by status or campaign.
Inputs: limit, status, campaign. Returns: result
publish_carouselB
Publish a carousel now. items: 2-10 of {"image_url": ...} or {"video_url": ...} (optional "alt_text" on images). Images must be JPEG. All slides are cropped to the first slide's ratio (4:5 to 1.91:1).
Inputs: items (required), caption, variant, campaign, +3 more. Returns: result
publish_imageA
Publish a single-image feed post now. Image must be a public HTTPS JPEG (Instagram's API does not take PNG) with an aspect ratio between 4:5 and 1.91:1. campaign/variant/hypothesis are stored locally for A/B comparison.
Inputs: image_url (required), caption, variant, alt_text, +4 more. Returns: result
publish_reelA
Publish a Reel now (MP4/MOV H.264+AAC, 9:16 recommended, max 300 MB). Give exactly one of video_url (public HTTPS) or video_path (file relative to the media root; a studio asset's video is refused: queue it from the website). trial_graduation makes it a trial Reel shown to non-followers first: SS_PERFORMANCE = Instagram shares it to followers if it performs, MANUAL = you decide in the app. Waits for video processing (can take minutes).
Inputs: caption, variant, campaign, cover_url, +8 more. Returns: result
publish_storyA
Publish a Story now (exactly one of image_url / video_url, 9:16; images JPEG). The API cannot add stickers, links or text overlays: bake them into the media.
Inputs: variant, campaign, image_url, video_url. Returns: result
rank_postsBRead-only
Score posts vs the account's own median (same type: feed/Reels/Stories),
with baseline posts read at a similar age. engagement_index 1.0 = typical.
A winner has enough reach (default 300) and either engagement >= the
threshold (default 1.5x) or reach >= 2x the median with engagement >= 1.0x.
Winners are the candidates to promote as ads. summary counts every post in
scope, before the only filter.
Inputs: only, limit, campaign. Returns: result
reply_to_commentB
Reply publicly to a top-level comment.
Inputs: message (required), comment_id (required). Returns: result
reschedule_postB
Move a pending/failed/cancelled post to a new time (re-arms it).
Inputs: post_id (required), publish_at (required). Returns: result
run_due_postsA
Publish every queued post whose time has come. Same as one scheduler pass.
Inputs: no named parameters. Returns: result
schedule_postB
Queue a post for later. A reel takes video_url or video_path (relative to the media root; a studio asset's video is refused). publish_at is ISO 8601; without an offset it is read in the configured time zone (default Europe/Paris), e.g. "2026-11-20T18:30". Needs the scheduler running (python -m src.scheduler daemon) or run_due_posts.
Inputs: kind (required), publish_at (required), items, caption, +11 more. Returns: result
search_hashtagARead-only
Top or recent public posts for a hashtag. Meta caps lookups at 30 unique hashtags per 7 days, so pick them deliberately.
Inputs: hashtag (required), edge, limit. Returns: result
send_dmA
Reply to a DM (only within 24h of the user's last message; user must write first). recipient_id is the Instagram-scoped ID from get_conversation_messages.
Inputs: message (required), recipient_id (required), page_id. Returns: result
validate_access_tokenBRead-only
Check that the configured access token works.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools map to a distinct resource+action: publish_image/carousel/reel/story differ by media type, and the schedule lifecycle (schedule_post, list_scheduled_posts, cancel_scheduled_post, reschedule_post, run_due_posts) is cleanly separated. A few boundaries blur — publish_reel vs schedule_post with a video, and three different insights tools (get_account_insights, get_media_insights, collect_insights) — but the descriptions resolve these for a careful agent.
Every tool is snake_case with a leading verb (get_, publish_, schedule_, cancel_, reschedule_, comment_, send_), producing a predictable and scannable surface. Minor outliers like run_due_posts and collect_insights still fit the verb_noun convention.
30 tools is above the comfortable band and the surface is broad (publishing, scheduling, insights, comments, DMs, A/B analysis, competitor benchmarking). Some pairs feel like they could be folded together (publish_* now vs schedule_post, get_media_insights vs collect_insights), making the set heavy even for a rich domain.
Coverage is unusually thorough: auth check, account/page discovery, publishing for all four formats, full scheduling lifecycle, account/media insights, comment moderation, DM read+reply, competitor benchmarking, and A/B comparison. Remaining gaps (no delete/archive of a published post, no edit-caption, no mention/tagging tools) are largely Instagram API limits and can be worked around in-app.
Maintenance
Related MCP Connectors
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.
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Lets Claude and AI agents post and schedule on Instagram, TikTok, LinkedIn and 5 more networks.
Related MCP Servers
- AlicenseAqualityCmaintenanceConnects Claude Desktop and other MCP clients to the Instagram Graph API for reading analytics, managing comments, and publishing photos, carousels, and reels.11125 npm1MIT
- 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.MIT
- AlicenseNot gradedqualityDmaintenanceConnects Claude to the official Meta Instagram Graph API (read-only) for retrieving Instagram profile, media, insights, and comments as MCP tools over Streamable HTTP.1MIT