Skip to main content
Glama
Instagram Campaign MCP

Instagram Campaign MCP

by enimarix

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 (daemon, run-due), retries, crash-safe

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

Authorization: Bearer header (token never in URLs/logs)

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_PERFORMANCE lets Instagram share it to followers if it performs; MANUAL leaves 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-only hourly. A Story that expired without such a snapshot is reported as incomplete.

  • 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-mcp

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File .\install.ps1 -RegisterClaudeCode

macOS / Linux:

./install.sh --register-claude-code

The installer:

  • creates .venv with 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 .env from env.example (never overwrites it);

  • writes mcp-config.json with this machine's paths, ready to paste into Claude Desktop;

  • with -RegisterClaudeCode / --register-claude-code, runs claude 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 -q

3. 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-due

A 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 above

Open 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_TOOLS in src/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=false skips them).

  • ~100 API-published posts per rolling 24h (get_publishing_limit shows 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 tools
cancel_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_variantsA
Read-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_commentA
Destructive

Permanently delete a comment. Prefer hide_comment unless the user asked.

Inputs: comment_id (required). Returns: result

get_account_insightsB
Read-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_pagesA
Read-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_commentsB
Read-only

Top-level comments on a post (with first-level replies).

Inputs: media_id (required), limit. Returns: result

get_competitor_profileB
Read-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_messagesC
Read-only

Messages in one DM conversation.

Inputs: conversation_id (required), limit, page_id. Returns: result

get_conversationsB
Read-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_insightsA
Read-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_postsB
Read-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_infoB
Read-only

Profile of the configured account: username, bio, followers, post count.

Inputs: account_id. Returns: result

get_publishing_limitA
Read-only

How many API posts were published in the last 24h vs the quota.

Inputs: no named parameters. Returns: result

hide_commentA
Idempotent

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_postsB
Read-only

Show the publishing queue, optionally filtered by status or campaign.

Inputs: limit, status, campaign. 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_postsB
Read-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_hashtagA
Read-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_tokenB
Read-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

    B3.2/5.0

    Scored across 30 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Connects Claude Desktop and other MCP clients to the Instagram Graph API for reading analytics, managing comments, and publishing photos, carousels, and reels.
      11
      125 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes Instagram actions (posts, media, comments, DMs, insights, Messenger profile) to Claude and ChatGPT via MCP.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude to the official Meta Instagram Graph API (read-only) for retrieving Instagram profile, media, insights, and comments as MCP tools over Streamable HTTP.
      1
      MIT