@mcpware/instagram-mcp

@mcpware/instagram-mcp

Instagram MCP server — 23 tools for the Instagram Graph API via Model Context Protocol.

Manage posts, comments, DMs, stories, hashtags, reels, carousels, and analytics from Claude Code, Cursor, or any MCP client.

Quick Start

npx @mcpware/instagram-mcp

Claude Code / Cursor .mcp.json

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "@mcpware/instagram-mcp"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your-meta-long-lived-token",
        "INSTAGRAM_ACCOUNT_ID": "your-ig-business-account-id"
      }
    }
  }
}

Prerequisites

• Instagram Business or Creator account (personal accounts are not supported by the Graph API)
• Facebook Page connected to your Instagram account
• Meta long-lived access token (see setup guide below)
• Instagram Business Account ID (obtained during setup)

Setup Guide — Getting Your Access Token

Meta's token setup is a multi-step process. Follow these steps carefully.

Step 1: Connect Instagram to a Facebook Page

Your IG Business/Creator account must be linked to a Facebook Page. Without this, the Graph API won't work.

• Open Instagram app → Settings → Account → Sharing to other apps → Facebook
• Select the Facebook Page to connect
• If you don't have a Page, create one at facebook.com/pages/creation

Step 2: Create a Meta Developer App

• Go to developers.facebook.com → Log in
• Click "Create App"
• App name: anything (e.g. "My IG Tool") — cannot contain "IG", "Instagram", "Facebook", etc.
• Use case: "Manage Instagram content and messaging" (under Content Management)
• Skip business portfolio for now
• Complete creation

Step 3: Add Permissions

• Go to your app → Use Cases → Customize → API setup with Facebook login
• Click "Add required content permissions" (adds instagram_basic, instagram_content_publish, pages_read_engagement, business_management, pages_show_list)
• Click "Add required messaging permissions" (adds instagram_manage_messages)

Step 4: Generate Access Token

• Go to Graph API Explorer
• Select your app from the "Meta App" dropdown
• Click "Get Token" → "Get User Access Token"
• Add permissions: instagram_basic, pages_show_list, pages_read_engagement, instagram_content_publish, instagram_manage_insights, instagram_manage_comments
• Click "Generate Access Token" → Authorize in the popup
• Copy the token

Note: The Graph API Explorer may show "No configuration available" if permissions aren't set up yet. Make sure Step 3 is done first.

Step 5: Get Your Instagram Business Account ID

In the Graph API Explorer, run:

GET /me/accounts?fields=id,name,instagram_business_account

Find your Page in the response. The instagram_business_account.id is your INSTAGRAM_ACCOUNT_ID.

Step 6: Exchange for Long-Lived Token (60 days)

The token from Step 4 expires in 1 hour. Exchange it:

curl "https://graph.facebook.com/v19.0/oauth/access_token?\
grant_type=fb_exchange_token&\
client_id=YOUR_APP_ID&\
client_secret=YOUR_APP_SECRET&\
fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"

Find your App ID and App Secret in: App Dashboard → Settings → Basic.

The returned access_token is valid for 60 days.

Step 7: Configure and Run

export INSTAGRAM_ACCESS_TOKEN="your-long-lived-token"
export INSTAGRAM_ACCOUNT_ID="your-ig-business-account-id"
npx @mcpware/instagram-mcp

Troubleshooting

Problem	Cause	Fix
me/accounts returns empty []	IG not connected to a Facebook Page, or you're not Page admin	Do Step 1
Graph API Explorer says "No configuration available"	Permissions not added to app	Do Step 3
"Generate Access Token" is disabled	Need to select "Get User Access Token" first	Click "Get Token" dropdown
App name rejected (contains "IG", "Insta", etc.)	Meta blocks trademarked words	Use a generic name
Token expired	Short-lived tokens last 1 hour	Do Step 6 for 60-day token
(#10) To use Instagram Graph API...	IG account is Personal, not Business	Switch to Business/Creator in IG settings

Environment Variables

Variable	Required	Default	Description
INSTAGRAM_ACCESS_TOKEN	Yes	—	Meta long-lived access token
INSTAGRAM_ACCOUNT_ID	Yes	—	Instagram business account ID
INSTAGRAM_API_VERSION	No	v19.0	Graph API version

Tools (23)

Profile & Account

Tool	Description
get_profile_info	Get profile info (bio, followers, media count)
get_account_pages	List connected Facebook pages
get_account_insights	Account-level analytics (reach, profile views)
validate_access_token	Check if token is valid

Media & Publishing

Tool	Description
get_media_posts	Get recent posts with engagement metrics
get_media_insights	Detailed analytics for a specific post
publish_media	Publish image or video
publish_carousel	Publish carousel (2-10 images/videos)
publish_reel	Publish a Reel
get_content_publishing_limit	Check daily publishing quota

Comments

Tool	Description
get_comments	Get comments on a post
post_comment	Post a comment
reply_to_comment	Reply to a comment
delete_comment	Delete a comment
hide_comment	Hide/unhide a comment

Direct Messages

Tool	Description
get_conversations	List DM conversations
get_conversation_messages	Read messages in a conversation
send_dm	Send a direct message

Discovery & Content

Tool	Description
search_hashtag	Search for a hashtag ID
get_hashtag_media	Get top/recent media for a hashtag
get_stories	Get current active stories
get_mentions	Get posts you're tagged in
business_discovery	Look up another business account

Limitations

These are Instagram Graph API limitations, not this tool's:

• Business/Creator accounts only — personal accounts are not supported
• Long-lived tokens expire after 60 days — refresh before expiry
• 200 API calls per hour rate limit
• 25 posts per day publishing limit
• DMs require Advanced Access — Meta app review required
• Hashtag search: 30 unique hashtags per 7 days

Credits

TypeScript rewrite of jlbadano/ig-mcp (Python).

License

MIT