instagram-mcp

2. Link an Instagram Business/Creator account

You need an Instagram account switched toBusinessorCreator, linked to a FacebookPage. In the app dashboard, walk throughInstagram → API setup with Facebook login → Step 1: Generate access tokensand link your account.

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 inDevelopment mode, only accounts in your app's Roles list (admins/developers/testers) can authenticate. That's fine for personal use. For other users, you needApp Reviewwith Advanced Access.

The fastest way: run the bundled helper.

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.envfor you.

# 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 thePage'saccess_token(never expires) and theinstagram_business_account.idof the linked IG account.

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

SetIG_GRAPH_HOST=graph.instagram.comif your token came from theInstagram Loginpath instead of Facebook Login.

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

- 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 windowon most Business accounts.
- send_dmis response-only by default— it only works inside the 24h user-initiated window. Pass amessage_tag(e.g.HUMAN_AGENT) to send outside that window. Tags require Meta approval.
- Some insight metrics needmetric_type='total_value'(Meta tightened this in 2024):views,accounts_engaged,total_interactions,profile_views,likes,comments,shares,saves.reachandfollower_countdon't.
- Errors return a structured dict, not exceptions. Look forerror: truealong withstatus,message,code,subcode, andfbtrace_idin the response — that's the Graph API error, not a Python traceback.