Provides tools for reading, publishing, commenting, and analyzing insights across Instagram Business/Creator accounts via the official Instagram Graph API.
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-mcp show my account insights for last 7 days"
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.
An MCP server for the official Instagram Graph API. Read, publish, comment, and pull analytics across one or many Instagram Business/Creator accounts from Claude (or any MCP client) — ToS-safe, no private/reverse-engineered API.
29 tools across accounts, media, publishing, insights, comments, discovery, and (review-gated) direct messages.
npx-style stdio MCP · Python · FastMCP · MITMost "Instagram automation" tools either (a) wrap the unofficial private API (username + password) — which violates Instagram's Terms and risks a ban — or (b) only post, with no way to read insights, comments, or mentions back. This server is built entirely on the official Graph API, is multi-account from day one, and covers the full read + write surface. The only thing it cannot do without Meta's approval is DMs (see Direct messages).
Related MCP server: instagram-mcp
An Instagram Professional account (Business or Creator). Personal accounts cannot use the Graph API. Converting is free and reversible (Instagram app → Settings → Account type).
The Instagram account connected to a Facebook Page.
A long-lived access token with instagram_basic + instagram_content_publish + instagram_manage_comments + instagram_manage_insights, and the account's numeric Instagram Business Account id. See SETUP.md for the exact token + id steps.
Python 3.10+.
From PyPI:
pip install adelaidasofia-instagram-mcpOr from source:
git clone https://github.com/adelaidasofia/instagram-mcp
cd instagram-mcp
python3 -m venv .venv && .venv/bin/pip install -e .Register it with your MCP client (Claude Desktop / Claude Code) — single-account zero-config path:
{
"mcpServers": {
"instagram": {
"command": "instagram-mcp",
"env": {
"INSTAGRAM_MCP_ACCESS_TOKEN": "EAA...your-long-lived-token...",
"INSTAGRAM_MCP_IG_USER_ID": "17841400000000000"
}
}
}
}instagram-mcp is the console script the package installs. From a source checkout it lives at .venv/bin/instagram-mcp, or run the module directly with python -m instagram_mcp.server.
Or skip the env vars and call add_account at runtime (token goes to your OS keychain). See Multiple accounts.
Accounts & health — healthcheck, list_accounts, add_account, set_default_account, remove_account, account_info
Profile & media — get_profile, list_media, get_media
Insights — get_account_insights (reach, impressions, profile views, follower count), get_media_insights (per-post reach, saves, shares, interactions), get_audience_insights (follower demographics: age, gender, country, city)
Publishing — publish_image, publish_video, publish_reel, publish_carousel (2–10 images), publish_story, publishing_limit (remaining 24h quota). Video/reel containers process asynchronously; the server polls to completion before publishing.
Comments — get_comments, reply_to_comment, hide_comment, delete_comment
Discovery — search_hashtag, get_hashtag_media, get_mentions, business_discovery (read any public Professional account by username)
Direct messages — list_conversations, get_messages, send_message (see below)
Publishing takes public https media URLs — Instagram fetches the bytes itself, so the image/video must be reachable on the open web (an S3/Cloudflare/any-CDN URL works).
Run one server for all your accounts (yours, a brand's, a client's). Each account authorizes its own token:
add_account(label="brand-a", access_token="EAA...", ig_user_id="178414...", make_default=True)
add_account(label="brand-b", access_token="EAA...", ig_user_id="178414...")
list_media(account="brand-b")
get_account_insights(account="brand-a")Tokens are stored in the macOS keychain (or a chmod 600 file on other platforms), never in the metadata file and never returned by any tool. Omit account on any tool to use the default.
The DM tools require the instagram_manage_messages permission, which Meta grants only through App Review (typically weeks, and stricter in 2025–2026). Until then, the DM tools fail loud with that instruction rather than silently no-op. Once your app is approved and the token carries the scope, set INSTAGRAM_MCP_DM_ENABLED=1. Note Instagram's 24-hour standard-messaging window applies.
Full App Review walkthrough (screencast shot list, reviewer test-instructions template, privacy-policy + business-verification requirements, post-approval flip, message-tag caveat): docs/APP_REVIEW.md.
Egress is pinned to the Meta host allow-list (graph.facebook.com / graph.instagram.com). A general SSRF guard (RFC1918 / loopback / link-local / CGNAT / cloud-metadata, fail-closed DNS) backs any URL handling.
Credentials never leak: every result and error passes a scrubber that strips access tokens (incl. Meta EAA… / IGQV…), bearer headers, app secrets, and API keys before it reaches the model.
Observability: every call appends a 4-field JSONL audit line (execution_time_ms, io, token_usage, error_class) under ~/.claude/instagram-mcp/audit.log.jsonl.
Input validation runs before every Graph call (ids, caption length, hashtag/username charset, https media URLs).
MIT — see LICENSE.
Built by Adelaida Diaz-Roa. Full install or team version at diazroa.com.
Live profile snapshot for one account: username, name, followers, media count, etc.
Inputs: account. Returns: object
Store an Instagram Business/Creator account for use by every tool.
label a short key you choose (e.g. "onde", "mycelium", "client-acme")
access_token a long-lived Instagram Graph API token (stored in the OS keychain)
ig_user_id the Instagram Business Account id (numeric)
app_secret optional Meta app secret — enables appsecret_proof call hardening
make_default set true to make this the account used when account is omitted
The token is written to the macOS keychain (or a chmod-600 file fallback) and is NEVER echoed back or logged.
Inputs: label (required), ig_user_id (required), access_token (required), app_secret, +1 more. Returns: object
Public profile + (optionally) recent media for ANY business/creator account by username.
Read-only competitor/prospect research via the business_discovery edge. Only works for Professional accounts (not personal). with_media pulls up to media_limit recent posts.
Inputs: username (required), account, with_media, media_limit. Returns: object
Permanently delete a comment you own (or a comment on your media). Irreversible.
Inputs: comment_id (required), account. Returns: object
Account-level analytics (reach, impressions, profile views, follower count).
metrics: comma-separated Graph metric names (default reach,impressions,profile_views, follower_count). period: day|week|days_28|lifetime. Exact available metrics vary by Graph API version; on a mismatch the Meta error names the correct metric.
Inputs: period, account, metrics. Returns: object
Follower demographics (age, gender, country, city).
Requires the account to have >=100 followers (Meta privacy floor) — below that the Graph returns an error, surfaced cleanly. Newer Graph versions use metric= follower_demographics with metric_type=total_value + breakdown=age|gender|country|city and a timeframe (last_14_days|last_30_days|last_90_days|prev_month) for engaged-audience metrics. All are override-able.
Inputs: metric, period, account, breakdown, +2 more. Returns: object
List comments on a media object (text, username, timestamp, like_count, hidden).
Inputs: media_id (required), limit, account. Returns: object
Recent or top media for a hashtag id. edge=top_media|recent_media. limit 1-100.
Get the hashtag_id from search_hashtag first. Subject to Meta's 30-unique-hashtags per-7-days query limit per account.
Inputs: hashtag_id (required), edge, limit, account. Returns: object
Return full fields for one media object by id (caption, type, permalink, like/comment counts).
Inputs: media_id (required), account. Returns: object
Per-post analytics (reach, saves, likes, comments, shares, total interactions).
metrics override is comma-separated; defaults suit feed posts. Reels/stories expose different metrics (e.g. plays, navigation) — pass them explicitly if needed.
Inputs: media_id (required), account, metrics. Returns: object
List recent media where the account is @-mentioned (tags edge).
Inputs: limit, account. Returns: object
Read messages in a DM conversation. REQUIRES Meta App Review (instagram_manage_messages).
Inputs: conversation_id (required), limit, account. Returns: object
Return the account's public profile fields (followers, follows, media count, bio, website).
Inputs: account. Returns: object
Verify the MCP is configured + ready: accounts present, token backend, Graph reachability.
Does a live GET on the default account's profile if one is configured. Safe to call anytime; never mutates. Returns ok=false with a hint when no account is set.
Inputs: no named parameters. Returns: object
Hide (or unhide) a comment from public view. hide=false unhides.
Inputs: comment_id (required), hide, account. Returns: object
List configured Instagram accounts (labels + ig_user_id + default flag). Never returns tokens.
Inputs: no named parameters. Returns: object
List Instagram DM conversations. REQUIRES Meta App Review (instagram_manage_messages).
Inputs: limit, account. Returns: object
List recent media (posts/reels) for the account, newest first. limit 1-100 (default 25).
Inputs: limit, account. Returns: object
Publish a multi-image carousel (2-10 images). Each image_url must be a PUBLIC https URL.
Creates one child container per image (is_carousel_item) then a CAROUSEL parent, then publishes.
Inputs: image_urls (required), account, caption. Returns: object
Publish a single image to the feed.
image_url must be a PUBLIC https URL (Instagram fetches the bytes itself). caption <= 2200 chars. Two-step Graph flow (create container -> publish) handled internally.
Inputs: image_url (required), account, caption. Returns: object
Remaining posts in the rolling 24h publishing quota (Instagram caps API posts/day).
Inputs: account. Returns: object
Publish a Reel. video_url must be a PUBLIC https URL.
share_to_feed also surfaces the reel in the main grid. cover_url (optional) sets the thumbnail. Reel containers process asynchronously (polled up to 90s).
Inputs: video_url (required), account, caption, cover_url, +1 more. Returns: object
Publish a Story (image OR video). Exactly one of image_url / video_url, PUBLIC https.
Inputs: account, image_url, video_url. Returns: object
Publish a video to the feed. video_url must be a PUBLIC https URL.
Video containers process asynchronously; this polls status up to 90s before publishing.
Inputs: video_url (required), account, caption. Returns: object
Remove a configured account + delete its stored token from the keychain.
Inputs: label (required). Returns: object
Reply to a comment. message <= 2200 chars. Returns the new comment id.
Inputs: message (required), comment_id (required), account. Returns: object
Resolve a hashtag name to its Graph id (needed before get_hashtag_media).
Inputs: hashtag (required), account. Returns: object
Send a DM. REQUIRES Meta App Review + the 24-hour standard-messaging window.
recipient_id is the IGSID (Instagram-scoped user id) of the recipient. Outside the 24h customer-service window a paid message tag is required (not handled here).
Inputs: text (required), recipient_id (required), account. Returns: object
Set which configured account is used when a tool's account arg is omitted.
Inputs: label (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 29 tools
Most tools have clearly distinct purposes (e.g., separate publish tools for image, video, reel, carousel, story; separate comment management tools). However, 'account_info' and 'get_profile' both return profile data with overlapping descriptions, causing potential confusion.
The majority follow a consistent verb_noun pattern (list_, add_, get_, publish_, etc.). Minor deviations include 'account_info' (noun_verb), 'business_discovery' (noun_noun), and 'publishing_limit' (gerund_noun), but these are not overly disruptive.
29 tools is on the higher end for a single domain, but each tool covers a distinct part of the Instagram Graph API (accounts, publishing, insights, comments, DMs, hashtags, mentions). The scope justifies the count, though it could be slightly trimmed.
The tool set covers most major Instagram API operations: account management, publishing (multiple formats), insights, comments, hashtags, mentions, and DMs. Missing update/delete for media and limited user search, but core workflows are well-covered.
Hosted MCP server for DataLikers — Instagram & TikTok data API. 51 tools: Instagram user search by demographics (gender/age/race/country/city), profiles, bulk lookup, engagement, posts & reels, comments, hashtags, locations, stories, highlights, music, business accounts, top users; TikTok users, videos, comments, hashtags, playlists and top charts. Streamable HTTP, Bearer API key. Free tier: 100 requests on signup at https://datalikers.com/p/1by27bwg
Instagram MCP for DM and comment automation, AI Agent and content publishing via Meta's official API
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Instagram data over MCP: profiles, posts, reels, stories, highlights and search as JSON
