instagram-mcp

A Model Context Protocol server that wraps the Instagram Graph API so Claude (or any MCP client) can read, publish, comment, DM, and pull insights from an Instagram Business or Creator account.

24 tools across five capability areas — profile/media, publishing, comments, DMs, and insights — built on FastMCP + httpx.

Quick install

pip install instagram-mcp

Or with uv:

uv tool install instagram-mcp

Setup

1. Create a Meta App

1. Go to https://developers.facebook.com/apps → Create app → use case Other → type Business.
2. In the app dashboard, add the Instagram product (Add Product → Instagram → Set up).

2. Link an Instagram Business/Creator account

You need an Instagram account switched to Business or Creator, linked to a Facebook Page. In the app dashboard, walk through Instagram → API setup with Facebook login → Step 1: Generate access tokens and link your account.

3. Get the required permissions

Generate a token with these scopes (in Graph API Explorer or the Instagram API setup page):

• instagram_basic
• instagram_content_publish
• instagram_manage_comments
• instagram_manage_messages
• instagram_manage_insights
• pages_show_list
• pages_read_engagement
• business_management

While your app is in Development mode, only accounts in your app's Roles list (admins/developers/testers) can authenticate. That's fine for personal use. For other users, you need App Review with Advanced Access.

4. Mint a long-lived Page token

The fastest way: run the bundled helper.

instagram-mcp-get-token

It will ask for your short-lived user token + app ID/secret, exchange it for a long-lived user token, list your linked IG accounts, and write .env for you.

Manual alternative:

# Exchange short-lived user token → long-lived (~60 days)
curl -G "https://graph.facebook.com/v21.0/oauth/access_token" \
  --data-urlencode "grant_type=fb_exchange_token" \
  --data-urlencode "client_id=YOUR_APP_ID" \
  --data-urlencode "client_secret=YOUR_APP_SECRET" \
  --data-urlencode "fb_exchange_token=SHORT_LIVED_TOKEN"

# Find your Pages and their IG accounts
curl -G "https://graph.facebook.com/v21.0/me/accounts" \
  --data-urlencode "fields=name,instagram_business_account,access_token" \
  --data-urlencode "access_token=LONG_LIVED_USER_TOKEN"

Use the Page's access_token (never expires) and the instagram_business_account.id of the linked IG account.

5. Configure .env

IG_USER_ID=17841446575432302
IG_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxxx
IG_GRAPH_VERSION=v21.0
IG_GRAPH_HOST=graph.facebook.com

Set IG_GRAPH_HOST=graph.instagram.com if your token came from the Instagram Login path instead of Facebook Login.

Connect to Claude Desktop

Edit ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "instagram": {
      "command": "instagram-mcp",
      "env": {
        "IG_USER_ID": "17841446575432302",
        "IG_ACCESS_TOKEN": "EAAxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. You should see 24 tools under the instagram server.

Available tools

Profile & media

| Tool | What it does | |---|---| | get_my_profile | Profile info: bio, followers, media count, etc. | | list_my_media | One page of recent posts | | list_all_media | Auto-paginate through all media | | get_media | Fetch a single media item | | list_tagged_media | Posts the account is tagged in | | list_stories | Currently-live stories (24h window) |

Hashtags

| Tool | What it does | |---|---| | search_hashtag | Resolve a #tag to its ID | | hashtag_top_media | Top-ranked posts for a hashtag | | hashtag_recent_media | Recent posts for a hashtag (24h window) |

Publishing

| Tool | What it does | |---|---| | publish_image | Single image post from a public URL | | publish_reel | Reel (waits for container processing) | | publish_story | Image or video story | | publish_carousel | 2-10 item carousel | | get_publish_limit | Show 24h publish quota usage |

Comments

| Tool | What it does | |---|---| | list_comments | Top-level comments + nested replies | | get_comment_replies | Replies under a specific comment | | reply_to_comment | Post a reply | | hide_comment | Hide / unhide | | delete_comment | Delete a comment you own |

Direct messages

| Tool | What it does | |---|---| | list_conversations | DM conversations | | get_conversation | Messages in a conversation | | send_dm | Send a DM (optionally with a message_tag) |

Insights

| Tool | What it does | |---|---| | get_account_insights | Account-level metrics with optional metric_type | | get_media_insights | Per-media insights |

Notes & gotchas

• Publishing requires public HTTPS URLs. Meta fetches media server-side. Host your images/videos on a publicly accessible URL first.
• Publish quota is 100 posts per 24h rolling window on most Business accounts.
• send_dm is response-only by default — it only works inside the 24h user-initiated window. Pass a message_tag (e.g. HUMAN_AGENT) to send outside that window. Tags require Meta approval.
• Some insight metrics need metric_type='total_value' (Meta tightened this in 2024): views, accounts_engaged, total_interactions, profile_views, likes, comments, shares, saves. reach and follower_count don't.
• Errors return a structured dict, not exceptions. Look for error: true along with status, message, code, subcode, and fbtrace_id in the response — that's the Graph API error, not a Python traceback.

Development

git clone https://github.com/AleemHaider/instagram-mcp
cd instagram-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.