Skip to main content
Glama
Instagram Campaign MCP

Instagram Campaign MCP

by enimarix

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
TIMEZONENoTimezone used for schedule times without an offset.Europe/Paris
MEDIA_ROOTNoDirectory containing asset files served at /api/media.
IG_MCP_HOMENoOverrides where the .env file and database are stored.
UI_PASSWORDNoPassword for the studio website when reviewing from another device.
DATABASE_PATHNoPath to the campaign database.
IG_MCP_PROFILENoTool profile. Use 'full' for all 30 tools or 'agent' for the read-only agent allow-list.full
MAX_LATE_MINUTESNoMaximum allowed lateness in minutes before a scheduled post is moved to the next free slot.30
WINNER_MIN_REACHNoMinimum reach required before a post can be called a winner.300
WINNER_THRESHOLDNoEngagement-index threshold for a post to qualify as a winner.1.5
PUBLISHING_PAUSEDNoSet to 'true' to hold the whole publishing queue.
MIN_SLOT_GAP_MINUTESNoMinimum gap in minutes between consecutive scheduled posts.
VALIDATE_IMAGE_RATIONoSet to 'false' to skip pre-publish image ratio validation.true
WINNER_MIN_AGE_HOURSNoMinimum age in hours before a post can be judged as a winner.
INSTAGRAM_ACCESS_TOKENYesLong-lived Meta user access token with the required Instagram Graph API permissions.
RATE_LIMIT_REQUESTS_PER_HOURNoClient-side cap on API calls per hour.200
INSTAGRAM_BUSINESS_ACCOUNT_IDNoInstagram 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:

  1. Research: search_hashtag, get_competitor_profile, rank_posts on past content.

  2. 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.

  3. Measure: collect_insights daily. Posts are judged after 48h (Stories after 20h).

  4. 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

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 after for the next page.

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 only filter.

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

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