ig-studio-mcp
Runs an Instagram professional (Creator or Business) account through Meta's official Graph API: reads profile and recent posts/reels, fetches per-post and account insights (reach, views, saves, shares, watch time, follows/unfollows), manages comments (read, reply, hide/unhide, delete), and publishes images and carousels with a publishing-quota check.
Uses Meta's Instagram API with Unified Login on graph.facebook.com, including Meta app credentials for token exchange, token expiry lookup via debug_token, renewal of expiring Facebook Login user tokens and appsecret_proof signing.
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., "@ig-studio-mcp How did my last 5 reels do?"
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.
ig-studio-mcp
Let Claude run your Instagram professional account through the official Graph API: analytics, comment management and publishing, all on your machine.
ig-studio-mcp is a local Model Context Protocol server that uses only Meta's official Instagram API with Unified Login (graph.facebook.com, Graph API v26.0). There's no scraping, no password login, and no Facebook Page required.
Contents
Related MCP server: instagram-claude-mcp
Features
Analytics: profile, recent posts and reels, per-post insights (reach, views, saves, shares, watch time) and account insights over 1, 7 or 28 days, including follows and unfollows.
Audience: age, gender, country and city of your followers (or of the people you reached or engaged), and the hours your followers are online, in your timezone.
Comment management: read, reply to, hide/unhide and delete comments.
Publishing: single images and carousels, plus a check of your daily publishing quota.
Safe by default: every tool that changes your account previews first and sends nothing until called again with
confirm=true.One setting: only an access token is required. The Instagram account is found from the token, and token expiry is read from Meta.
Private: runs locally over stdio. The token stays in your
.envand is never logged or returned in tool output.
Quick start
You need:
An Instagram Creator or Business account
A Meta app using the Instagram API with Unified Login
uv and Python 3.11+
1. Install
git clone https://github.com/Luffy610/ig-studio-mcp.git
cd ig-studio-mcp
uv sync2. Get a token. Follow the step-by-step guide in docs/TOKEN_SETUP.md. It takes about 15 minutes and needs no App Review.
3. Configure. Copy the example file:
cp .env.example .envThen set the one required value in .env:
IG_ACCESS_TOKEN=EAA...4. Check
uv run ig-studio-mcp checkToken: SYSTEM_USER for app 'my app', never expires
Instagram accounts reachable: @your_handle (1784...)
OK - using @your_handle (id 1784..., 1234 followers)Connect to Claude
Claude Desktop
Add the server to claude_desktop_config.json. On Windows the file is at %APPDATA%\Claude\claude_desktop_config.json; on macOS it's at ~/Library/Application Support/Claude/claude_desktop_config.json.
{
"mcpServers": {
"ig-studio": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ig-studio-mcp", "run", "ig-studio-mcp"]
}
}
}On Windows, write the path with escaped backslashes, e.g. "C:\\path\\to\\ig-studio-mcp". Restart Claude Desktop afterwards.
Claude Code
claude mcp add ig-studio --scope user -- uv --directory /absolute/path/to/ig-studio-mcp run ig-studio-mcpMCP Inspector
From the project folder, run:
npx @modelcontextprotocol/inspector uv run ig-studio-mcpOpen the URL it prints, click Connect, then go to Tools → List Tools.
Try asking Claude:
"How did my last 5 reels do?"
"Where are my followers from, and when is the best time to post?"
"Summarise the comments on my latest post and draft replies."
"Hide the spam comments on my last reel."
Tools
Tool | What it does | Key arguments | Permission |
| Username, name, bio, website, followers, follows, media count | none |
|
| Recent posts and reels (newest first) with caption, type, time, likes, comments, link |
|
|
| Top-level comments: id, username, text, time, likes, reply count |
|
|
| Lifetime metrics for a post, reel or story; metrics chosen by media type |
|
|
| Account totals for the last 1, 7 or 28 days, including follows and unfollows |
|
|
| Age, gender, country and city of followers, or of the engaged or reached audience |
|
|
| Average followers online for each hour of the day, plus the best 3 hours |
|
|
| Post a public reply |
|
|
| Hide, or unhide with |
|
|
| Permanently delete a comment on your media |
|
|
| Publish one JPEG with a caption |
|
|
| Publish 2-10 JPEGs as one post |
|
|
| API posts used and remaining in the rolling 24 hours | none |
|
Notes:
Media insights: feed posts and carousels return reach, views, likes, comments, saves, shares, total_interactions, profile_visits and follows. Reels add
ig_reels_avg_watch_timeandig_reels_video_view_total_time(in ms). Stories return reach, views, shares, replies, navigation, follows, profile_visits and total_interactions.Missing metrics: if Instagram doesn't return a metric for an item, it's listed under
unavailable; the rest of the call still succeeds.Deprecated metrics are never requested:
impressions,plays,video_views,profile_views,website_clicks,engagement.
Write tools need confirmation
Every write tool takes confirm, which defaults to false. With confirm=false the tool sends nothing to Instagram. Instead it returns a preview: the action, the exact text, and the API call it would make. Claude is told to show you the preview and call again with confirm=true only after you approve. In every result, executed tells you whether anything was actually sent.
Publishing
A publish takes three steps:
Create a media container.
Check the container's
status_codeuntil it'sFINISHED. Images are usually ready right away; the server gives up after about 4 minutes, within Meta's 5-minute guidance.Publish the container.
If any step fails, nothing is posted. Images must be public JPEG URLs, at most 8 MB, with an aspect ratio between 4:5 and 1.91:1. Captions can have up to 2,200 characters, 30 hashtags and 20 @mentions, and are checked before anything is sent.
Configuration
Settings are read from .env, which is git-ignored. See .env.example for the full list.
Variable | Required | Purpose |
| yes | Token from API setup with Unified login → Generate access tokens (starts with |
| no | Which Instagram account to use, if the token can reach several. |
| no | Meta app credentials (App settings → Basic). Needed only for expiring Facebook Login user tokens. If the secret is set, every call also sends |
| no | Path to a different |
How settings are found:
Where
.envcomes from:$IG_STUDIO_ENV_FILE, then./.env, then the project root's.env.Precedence: values in
.envoverride process environment variables.No restart needed: the file is re-read on every call, so a new token takes effect immediately.
Account discovery. Unified Login system-user tokens find the account through /me/assigned_instagram_accounts. Facebook Login user tokens fall back to the Page-linked account in /me/accounts.
Token expiry. System-user tokens usually never expire. For tokens that do expire, the server reads the expiry from debug_token. If META_APP_ID and META_APP_SECRET are set, it renews a Facebook Login user token when it's within 10 days of expiry. Unified Login tokens with an expiry date have to be regenerated (see docs/TOKEN_SETUP.md).
CLI
Command | Purpose |
| Run the MCP server over stdio (what Claude launches) |
| Show the token type, expiry and missing permissions, list reachable accounts, and fetch the profile |
| Renew an expiring Facebook Login user token (does nothing for tokens that never expire) |
| Swap a short-lived Facebook Login user token for a long-lived one (needs |
Limits worth knowing
Insights lag: data can be up to 48 hours behind.
Story insights exist for only 24 hours and need at least 5 viewers.
Items inside a carousel have no insights of their own.
Follower and audience metrics (follows/unfollows, demographics, active hours) need 100+ followers, or 100+ engagements in the timeframe for the engaged audience.
Demographics:
timeframecan only bethis_weekorthis_month, and only affects the engaged and reached audiences.Cities are limited to the top 45.
Active hours cover at most the last 30 days. Instagram reports them in Pacific time, and the server converts them to the
timezoneyou pass.
Comments:
get_media_commentsreturns top-level comments only. Replies are counted, not listed.Hidden comments disappear from the list, so keep the ID if you may want to unhide one.
Rate limits: Instagram rate-limits calls per account over a rolling 24 hours. When Meta says how long to wait, rate-limit errors include it.
Publishing quota: 100 API posts per rolling 24 hours, with a carousel counting as one. Some of Meta's docs still say 50, so check yours with
get_publishing_limit.API version: pinned in one place,
GRAPH_API_VERSIONinclient.py.
Development
uv sync # install, including dev tools
uv run pytest # 120+ tests, all HTTP mocked; no Instagram account needed
uv run ruff check . # lint
uv run ruff format . # formatCode layout:
File | Responsibility |
MCP tool definitions only | |
Every HTTP call | |
Credentials and the | |
Trimmed response models | |
Meta error codes → actionable messages | |
Command-line entry point |
CI runs lint, tests on Python 3.11 to 3.14 (plus Windows and macOS) and a package build on every push and pull request.
Contributing
Contributions are welcome. Please read CONTRIBUTING.md and the Code of Conduct, and check the changelog for what changed recently.
Security
Please report vulnerabilities privately; see SECURITY.md. Never paste access tokens or .env contents into issues.
License
MIT © 2026 Dhruv Kotwani
Disclaimer
This project is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. or Instagram. "Instagram", "Facebook" and "Meta" are trademarks of Meta Platforms, Inc. Use it only with accounts you own or manage, and follow Meta's Platform Terms.
Available Tools
13 toolsdelete_commentADestructiveIdempotent
Permanently delete a comment on the user's media. Cannot be undone.
Only use when the user clearly wants the comment gone; suggest hide_comment as the reversible alternative. ALWAYS call with confirm=false first to get a preview (nothing is sent), and only call with confirm=true after the user explicitly approves deleting it.
Args: comment_id: The comment to delete (from get_media_comments). confirm: false = preview only (default); true = permanently delete.
Returns: executed (false for previews), summary and success. Limits: only works on comments on the user's own media; live-video comments are not supported.
Inputs: comment_id (required), confirm. Returns: Preview (executed=false) or result (executed=true) of a comment write.
get_account_insightsARead-only
Get account-level totals for a recent window: the last 1, 7 or 28 days ending now.
Use this when the user asks how their account is doing overall (reach, engagement, follower growth) rather than about a single post.
Args: period: "day" (last 24h), "week" (last 7 days) or "days_28" (last 28 days).
Returns: metrics {name: total} — reach, views, accounts_engaged, total_interactions,
likes, comments, shares, saves, replies, profile_links_taps, follows (new followers)
and unfollows —
plus unavailable and notes. Some metrics need 100+ followers. Data can lag up to 48 hours.
Inputs: period. Returns: notes, since, until, period, +2 more
get_audience_demographicsARead-only
Who the audience is: age, gender, country and city breakdowns.
Use when the user asks about their followers' or viewers' demographics: age groups, gender split, top countries or cities.
Args: audience: "followers" (current followers, default), "engaged" (accounts that interacted with content in the timeframe) or "reached" (accounts that saw content in the timeframe). breakdown: "all" (age, gender, country and city; default), one of those, or "age_gender" for the combined split (e.g. "25-34, male"). timeframe: "this_week" or "this_month" (default). Affects engaged and reached only.
Returns: breakdowns {name: [{label, value, percent}]} sorted largest first, plus unavailable
and notes. Countries are ISO codes (IN, US). Cities are limited to the top 45.
Limits: needs 100+ followers (or 100+ engagements in the timeframe for engaged/reached).
Inputs: audience, breakdown, timeframe. Returns: notes, audience, timeframe, breakdowns, +1 more
get_follower_active_hoursARead-only
When followers are online: average followers on Instagram for each hour of the day.
Use when the user asks when their followers are most active or the best time to post. Pass the user's own timezone so the hours are local to them.
Args: days: How many recent days to average, 1-30 (default 30, the maximum Instagram allows). timezone: IANA timezone for the hours, e.g. "Asia/Kolkata", "America/New_York" (default "UTC").
Returns: hours [{hour, avg_online_followers}] for 0-23, best_hours (top 3, best first), days_with_data and notes. Limits: needs 100+ followers; Instagram keeps only the last 30 days of this data.
Inputs: days, timezone. Returns: hours, notes, timezone, best_hours, +2 more
get_media_commentsARead-only
Get top-level comments on one post or reel, newest first.
Use this to read audience feedback or find comment IDs to reply to / moderate. Get media_id from list_recent_media. Replies are not listed, only counted.
Args: media_id: The Instagram media ID. limit: Max comments to return, 1-500 (default 50).
Returns: comments[] with id, username, text, timestamp, like_count, hidden, reply_count (reply_count_is_partial=true means there are more replies than counted); has_more if more comments exist. Comments on age-gated media and comments hidden with hide_comment are not returned by Instagram.
Inputs: media_id (required), limit. Returns: count, comments, has_more, media_id
get_media_insightsARead-only
Get lifetime performance metrics for one post, reel or story.
Use this when the user asks how a specific piece of content performed. Get media_id from list_recent_media. Metrics depend on the media type and are picked automatically:
Feed posts/carousels: reach, views, likes, comments, saves, shares, total_interactions, profile_visits, follows
Reels: reach, views, likes, comments, saves, shares, total_interactions, ig_reels_avg_watch_time and ig_reels_video_view_total_time (milliseconds)
Stories: reach, views, shares, replies, navigation, follows, profile_visits, total_interactions
Returns: metrics {name: value}, unavailable lists metrics Instagram didn't return,
and notes. Data can lag up to 48 hours; items inside a carousel have no insights.
Inputs: media_id (required). Returns: notes, metrics, media_id, media_type, +2 more
get_profileARead-only
Get the connected Instagram account's profile.
Use this first to confirm which account is connected, or when the user asks about their follower count, bio, or how many posts they have.
Returns: id, username, name, biography, website, followers_count, follows_count, media_count.
Inputs: no named parameters. Returns: id, name, website, username, +4 more
get_publishing_limitARead-only
Check how many posts the account can still publish through the API in the rolling 24 hours.
Use before publishing, or when a publish fails with a daily-limit error.
Returns: quota_usage (posts published via the API in the window), quota_total, quota_duration_hours and remaining.
Inputs: no named parameters. Returns: API publishing quota for the rolling 24 hours.
hide_commentAIdempotent
Hide (or unhide) a comment on the user's media. Reversible.
Hidden comments disappear for everyone except their author. Prefer this over delete_comment for spam or abuse, since it can be undone with hide=false. ALWAYS call with confirm=false first to get a preview (nothing is sent), and only call with confirm=true after the user approves.
Args: comment_id: The comment to hide or unhide (from get_media_comments). hide: true to hide (default), false to unhide. confirm: false = preview only (default); true = actually do it.
Returns: executed (false for previews), summary and success. Limits: comments the account owner wrote on their own media always stay visible. Hidden comments no longer appear in get_media_comments, so tell the user the comment_id if they may want to unhide it later.
Inputs: comment_id (required), hide, confirm. Returns: Preview (executed=false) or result (executed=true) of a comment write.
list_recent_mediaARead-only
List the account's most recent posts and reels (newest first). Stories are not included.
Use this to find media IDs for get_media_comments / get_media_insights, or to review recent content and its engagement at a glance.
Args: limit: How many items to return, 1-100 (default 10).
Returns: items[] with id, caption, media_type (IMAGE/VIDEO/CAROUSEL_ALBUM), media_product_type (FEED/REELS), timestamp (UTC), like_count (absent if likes are hidden), comments_count, permalink; plus has_more if older media exists.
Inputs: limit. Returns: count, items, has_more
publish_carouselA
Publish a carousel (several photos in one post) to the user's feed. Public and immediate.
Use only when the user explicitly asks to post several photos together. ALWAYS call with confirm=false first to get a preview (nothing is sent), and call with confirm=true only after the user approves.
Args: image_urls: 2-10 public JPEG URLs, in display order. Every image is cropped to the first image's aspect ratio. caption: Post text, same limits as publish_image. confirm: false = preview only (default); true = publish.
Returns: executed, summary, container_ids (children then parent), and media_id + permalink. Limits: counts as one post toward the daily limit.
Inputs: image_urls (required), caption, confirm. Returns: Preview (executed=false) or result (executed=true) of publishing a post.
publish_imageA
Publish a single photo to the user's Instagram feed. Public and immediate.
Use only when the user explicitly asks to post. ALWAYS call with confirm=false first: that returns a preview (image URL, exact caption, warnings) and sends nothing. Show it to the user and call again with confirm=true only after they approve.
Args: image_url: Public URL of a JPEG that Instagram can download (no login or expiring link). Max 8 MB, aspect ratio between 4:5 and 1.91:1, width 320-1440 px. caption: Post text. Max 2,200 characters, 30 hashtags, 20 @mentions. confirm: false = preview only (default); true = publish.
Returns: executed, summary, container_ids, and media_id + permalink once published. Limits: a capped number of API posts per rolling 24 hours (see get_publishing_limit). Publishing usually takes seconds but can take up to ~5 minutes while Instagram processes it.
Inputs: image_url (required), caption, confirm. Returns: Preview (executed=false) or result (executed=true) of publishing a post.
reply_to_commentA
Post a public reply to a comment on the user's media, as the user's account.
Use when the user wants to answer a comment. Get comment_id from get_media_comments. ALWAYS call with confirm=false first: that returns a preview and sends nothing. Show the preview to the user and only call again with confirm=true after they explicitly approve.
Args: comment_id: The comment to reply to. message: Exact reply text (posted as-is, publicly). confirm: false = preview only (default); true = actually post.
Returns: executed (false for previews), summary, the exact message, and reply_id once posted. Limits: replies always attach to the top-level comment (replying to a reply adds to its parent's thread); hidden comments and comments on live videos can't be replied to.
Inputs: message (required), comment_id (required), confirm. Returns: Preview (executed=false) or result (executed=true) of a comment write.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct resource and action: profile, media listing, comments, media insights, account insights, demographics, active hours, comment moderation, publishing, and publishing limits. The read/write pairs for comments and the image/carousel publishing tools are clearly separated by their specific purposes.
All tool names use consistent snake_case and follow a predictable verb_noun or verb_preposition_noun pattern. Even the slightly longer names like get_follower_active_hours and get_audience_demographics remain readable and consistent with the rest.
Thirteen tools is well-scoped for an Instagram account management surface. Each tool covers a meaningful operation, and there is no obvious filler or trivial tool.
The server covers profile reading, media listing, comments, insights, audience analytics, commenting actions, and photo/carousel publishing. Minor gaps remain around publishing video/reels, deleting own media, or managing stories, but core workflows are well-supported.
Maintenance
Related MCP Connectors
Create and manage Instagram DM and comment-reply automations by talking to Claude.
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Lets Claude and AI agents post, schedule and measure on Instagram, TikTok, LinkedIn and 5 more.
Create, schedule and publish Instagram and Facebook posts from Claude or ChatGPT.
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 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
- AlicenseNot gradedqualityCmaintenanceConnects Claude to Instagram through Meta's official API, enabling users to retrieve account insights, analyze professional profiles, publish photos/carousels/reels/stories, manage comments, read and respond to Direct messages, and call any Graph API endpoint.MIT
- AlicenseNot gradedqualityCmaintenanceEnables a single professional Instagram account to be managed through Claude, including reading and replying to comments and direct messages, and viewing account and media statistics. It runs as a remote streamable HTTP server with OAuth-protected access and automatic renewal of the Instagram token.MIT