Skip to main content
Glama
ig-studio-mcp

ig-studio-mcp

by Luffy610

ig-studio-mcp

CI License: MIT Python 3.11+ 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 .env and 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 sync

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

Then set the one required value in .env:

IG_ACCESS_TOKEN=EAA...

4. Check

uv run ig-studio-mcp check
Token: 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-mcp

MCP Inspector

From the project folder, run:

npx @modelcontextprotocol/inspector uv run ig-studio-mcp

Open 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

get_profile

Username, name, bio, website, followers, follows, media count

none

instagram_basic

list_recent_media

Recent posts and reels (newest first) with caption, type, time, likes, comments, link

limit 1-100

instagram_basic

get_media_comments

Top-level comments: id, username, text, time, likes, reply count

media_id, limit 1-500

instagram_manage_comments

get_media_insights

Lifetime metrics for a post, reel or story; metrics chosen by media type

media_id

instagram_manage_insights

get_account_insights

Account totals for the last 1, 7 or 28 days, including follows and unfollows

period: day, week, days_28

instagram_manage_insights

get_audience_demographics

Age, gender, country and city of followers, or of the engaged or reached audience

audience, breakdown, timeframe

instagram_manage_insights

get_follower_active_hours

Average followers online for each hour of the day, plus the best 3 hours

days 1-30, timezone

instagram_manage_insights

reply_to_comment

Post a public reply

comment_id, message, confirm

instagram_manage_comments

hide_comment

Hide, or unhide with hide=false. Reversible

comment_id, hide, confirm

instagram_manage_comments

delete_comment

Permanently delete a comment on your media

comment_id, confirm

instagram_manage_comments

publish_image

Publish one JPEG with a caption

image_url, caption, confirm

instagram_content_publish

publish_carousel

Publish 2-10 JPEGs as one post

image_urls, caption, confirm

instagram_content_publish

get_publishing_limit

API posts used and remaining in the rolling 24 hours

none

instagram_content_publish

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_time and ig_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:

  1. Create a media container.

  2. Check the container's status_code until it's FINISHED. Images are usually ready right away; the server gives up after about 4 minutes, within Meta's 5-minute guidance.

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

IG_ACCESS_TOKEN

yes

Token from API setup with Unified login → Generate access tokens (starts with EAA). See docs/TOKEN_SETUP.md.

IG_ACCOUNT_ID

no

Which Instagram account to use, if the token can reach several. check lists them.

META_APP_ID, META_APP_SECRET

no

Meta app credentials (App settings → Basic). Needed only for expiring Facebook Login user tokens. If the secret is set, every call also sends appsecret_proof.

IG_STUDIO_ENV_FILE

no

Path to a different .env file. This one is a process environment variable, not a .env entry.

How settings are found:

  • Where .env comes from: $IG_STUDIO_ENV_FILE, then ./.env, then the project root's .env.

  • Precedence: values in .env override 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

uv run ig-studio-mcp

Run the MCP server over stdio (what Claude launches)

uv run ig-studio-mcp check

Show the token type, expiry and missing permissions, list reachable accounts, and fetch the profile

uv run ig-studio-mcp refresh-token

Renew an expiring Facebook Login user token (does nothing for tokens that never expire)

uv run ig-studio-mcp exchange-token

Swap a short-lived Facebook Login user token for a long-lived one (needs META_APP_ID and META_APP_SECRET)

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: timeframe can only be this_week or this_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 timezone you pass.

  • Comments:

    • get_media_comments returns 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_VERSION in client.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 .       # format

Code layout:

File

Responsibility

server.py

MCP tool definitions only

client.py

Every HTTP call

auth.py

Credentials and the .env file

models.py

Trimmed response models

errors.py

Meta error codes → actionable messages

cli.py

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 tools
delete_commentA
DestructiveIdempotent

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_insightsA
Read-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_demographicsA
Read-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_hoursA
Read-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_commentsA
Read-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_insightsA
Read-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_profileA
Read-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_limitA
Read-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_commentA
Idempotent

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_mediaA
Read-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_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

    A4.6/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    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
      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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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