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

1. Open Instagram app → Settings → Account → Sharing to other apps → Facebook

2. Select the Facebook Page to connect

3. If you don't have a Page, create one at facebook.com/pages/creation

Step 2: Create a Meta Developer App

1. Go to developers.facebook.com → Log in

2. Click "Create App"

3. App name: anything (e.g. "My IG Tool") — cannot contain "IG", "Instagram", "Facebook", etc.

4. Use case: "Manage Instagram content and messaging" (under Content Management)

5. Skip business portfolio for now

6. Complete creation

Step 3: Add Permissions

1. Go to your app → Use Cases → Customize → API setup with Facebook login

2. Click "Add required content permissions" (adds instagram_basic, instagram_content_publish, pages_read_engagement, business_management, pages_show_list)

3. Click "Add required messaging permissions" (adds instagram_manage_messages)

Step 4: Generate Access Token

1. Go to Graph API Explorer

2. Select your app from the "Meta App" dropdown

3. Click "Get Token" → "Get User Access Token"

4. Add permissions: instagram_basic, pages_show_list, pages_read_engagement, instagram_content_publish, instagram_manage_insights, instagram_manage_comments

5. Click "Generate Access Token" → Authorize in the popup

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

Environment Variables

Tools (23)

Profile & Account

Media & Publishing

Comments

Direct Messages

Discovery & Content

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