Instagram Campaign MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TIMEZONE | No | Timezone used for schedule times without an offset. | Europe/Paris |
| MEDIA_ROOT | No | Directory containing asset files served at /api/media. | |
| IG_MCP_HOME | No | Overrides where the .env file and database are stored. | |
| UI_PASSWORD | No | Password for the studio website when reviewing from another device. | |
| DATABASE_PATH | No | Path to the campaign database. | |
| IG_MCP_PROFILE | No | Tool profile. Use 'full' for all 30 tools or 'agent' for the read-only agent allow-list. | full |
| MAX_LATE_MINUTES | No | Maximum allowed lateness in minutes before a scheduled post is moved to the next free slot. | 30 |
| WINNER_MIN_REACH | No | Minimum reach required before a post can be called a winner. | 300 |
| WINNER_THRESHOLD | No | Engagement-index threshold for a post to qualify as a winner. | 1.5 |
| PUBLISHING_PAUSED | No | Set to 'true' to hold the whole publishing queue. | |
| MIN_SLOT_GAP_MINUTES | No | Minimum gap in minutes between consecutive scheduled posts. | |
| VALIDATE_IMAGE_RATIO | No | Set to 'false' to skip pre-publish image ratio validation. | true |
| WINNER_MIN_AGE_HOURS | No | Minimum age in hours before a post can be judged as a winner. | |
| INSTAGRAM_ACCESS_TOKEN | Yes | Long-lived Meta user access token with the required Instagram Graph API permissions. | |
| RATE_LIMIT_REQUESTS_PER_HOUR | No | Client-side cap on API calls per hour. | 200 |
| INSTAGRAM_BUSINESS_ACCOUNT_ID | No | Instagram Business or Creator account ID. If omitted, you can connect with only the token and call get_account_pages to discover it. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Instagram organic campaign toolkit (official Graph API, Business/Creator account).
Typical loop:
Research: search_hashtag, get_competitor_profile, rank_posts on past content.
Plan & publish: publish_* now, or schedule_post for later. Tag every post with campaign + variant + hypothesis so A/B results can be compared. Trial Reels (publish_reel trial_graduation) test a Reel on non-followers first.
Measure: collect_insights daily. Posts are judged after 48h (Stories after 20h).
Decide: rank_posts(only="winner") lists posts beating the account median; compare_variants(campaign) says which variant is ahead.
Media must be at a public HTTPS URL; Instagram downloads it. Reels may instead use
video_path (relative to the studio media root), uploaded directly. Scheduled posts are
published by python -m src.scheduler daemon (or run_due_posts) - the API itself
cannot schedule. Publishing is irreversible: confirm captions and media with the
user before publishing on their behalf.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| validate_access_tokenB | Check that the configured access token works. |
| get_account_pagesA | List Facebook Pages for this token and their linked Instagram account IDs (use the id as INSTAGRAM_BUSINESS_ACCOUNT_ID). |
| get_profile_infoB | Profile of the configured account: username, bio, followers, post count. |
| get_account_insightsB | 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). |
| get_publishing_limitA | How many API posts were published in the last 24h vs the quota. |
| get_media_postsB | Recent posts (newest first) with type, caption, permalink, likes, comments.
Pass next_cursor as |
| get_media_insightsA | Insights for one post. Metrics are picked automatically for feed posts, Reels or Stories unless given. |
| 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. |
| 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). |
| 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). |
| 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. |
| 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. |
| list_scheduled_postsB | Show the publishing queue, optionally filtered by status or campaign. |
| cancel_scheduled_postA | Cancel a pending or failed scheduled post (a pending studio asset goes back to approved). |
| reschedule_postB | Move a pending/failed/cancelled post to a new time (re-arms it). |
| run_due_postsA | Publish every queued post whose time has come. Same as one scheduler pass. |
| get_commentsB | Top-level comments on a post (with first-level replies). |
| reply_to_commentB | Reply publicly to a top-level comment. |
| comment_on_mediaA | Add a comment from the account on one of its own posts (e.g. a pinned CTA). |
| hide_commentA | Hide (or unhide) a comment. Reversible, unlike delete. |
| delete_commentA | Permanently delete a comment. Prefer hide_comment unless the user asked. |
| search_hashtagA | Top or recent public posts for a hashtag. Meta caps lookups at 30 unique hashtags per 7 days, so pick them deliberately. |
| get_competitor_profileB | Public stats and recent posts (likes, comments, captions) of another Business/Creator account, for benchmarking. |
| 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. |
| rank_postsB | 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 |
| compare_variantsA | 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. |
| label_postA | Attach campaign/variant/hypothesis to an existing post (e.g. one published from the app) so it counts in compare_variants. |
| get_conversationsB | Instagram DM conversations (needs instagram_manage_messages). page_id defaults to the Facebook Page linked to the configured Instagram account. |
| get_conversation_messagesC | Messages in one DM conversation. |
| 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.