@mcpware/instagram-mcp

A Model Context Protocol (MCP) server that provides seamless integration with Instagram's Graph API, enabling AI applications to interact with Instagram Business accounts programmatically.

Features

🔧 Tools (Model-controlled)

- Get Profile Info: Retrieve Instagram business profile details - Get Media Posts: Fetch recent posts from an Instagram account - Get Media Insights: Retrieve engagement metrics for specific posts - Publish Media: Upload and publish images/videos to Instagram - Get Account Pages: List Facebook pages connected to the account - Get Conversations: List Instagram DM conversations (requires Advanced Access) - Get Conversation Messages: Read messages from specific conversations (requires Advanced Access) - Send DM: Reply to Instagram direct messages (requires Advanced Access)

📊 Resources (Application-controlled)

- Profile Data: Access to profile information including follower counts, bio, etc. - Media Feed: Recent posts with engagement metrics - Insights Data: Detailed analytics for posts and account performance

💬 Prompts (User-controlled)

- Analyze Engagement: Pre-built prompt for analyzing post performance - Content Strategy: Template for generating content recommendations - Hashtag Analysis: Prompt for hashtag performance evaluation

Prerequisites

1. Instagram Business Account: Must be connected to a Facebook Page
2. Facebook Developer Account: Required for API access
3. Access Token: Long-lived access token with appropriate permissions
4. Python 3.10+: For running the MCP server (required by MCP dependencies)

Required Instagram API Permissions

Standard Access (available immediately):
- instagram_basic
- instagram_content_publish
- instagram_manage_insights
- instagram_manage_comments
- pages_show_list
- pages_read_engagement
- pages_manage_metadata
- pages_read_user_content
- business_management

Advanced Access (requires Meta App Review):
- instagram_manage_messages - Required for Direct Messaging features

> ⚠️ Instagram DM Features: Reading and sending Instagram direct messages requires Advanced Access approval from Meta. See INSTAGRAM_DM_SETUP.md for the App Review process.

🔑 How to Get Instagram API Credentials

> 📖 Quick Start: See AUTHENTICATION_GUIDE.md for a 5-minute setup guide!

This section provides a step-by-step guide to obtain the necessary credentials for the Instagram MCP server.

Step 1: Set Up Instagram Business Account

1. Convert to Business Account (if not already):
- Open Instagram app → Settings → Account → Switch to Professional Account
- Choose "Business" → Select a category → Complete setup

2. Connect to Facebook Page:
- Go to Instagram Settings → Account → Linked Accounts → Facebook
- Connect to an existing Facebook Page or create a new one
- Important: The Facebook Page must be owned by you

Step 2: Create Facebook App

1. Go to Facebook Developers:
- Visit developers.facebook.com
- Log in with your Facebook account

2. Create New App:
- Click "Create App" → Choose "Business" → Click "Next"
- Fill in app details:
- App Name: Choose a descriptive name (e.g., "My Instagram MCP Server")
- App Contact Email: Your email address
- Click "Create App"

3. Add Instagram Basic Display Product:
- In your app dashboard, click "Add Product"
- Find "Instagram Basic Display" → Click "Set Up"

4. Configure Instagram Basic Display:
- Go to Instagram Basic Display → Basic Display
- Click "Create New App" in the Instagram App section
- Accept the terms and create the app

Step 3: Get App Credentials

1. Get App ID and Secret:
- In your Facebook app dashboard, go to Settings → Basic
- Copy your App ID and App Secret
- Important: Keep the App Secret secure and never share it publicly

Step 4: Set Up Instagram Business API Access

1. Add Instagram Graph API Product:
- In your app dashboard, click "Add Product"
- Find "Instagram Graph API" → Click "Set Up"

2. Configure Permissions:
- Go to Instagram Graph API → Permissions
- Request the following permissions:
- instagram_basic
- instagram_content_publish
- instagram_manage_insights
- pages_show_list
- pages_read_engagement

Step 5: Generate Access Token

Option A: Using Facebook Graph API Explorer (Recommended for Testing)

1. Go to Graph API Explorer:
- Visit developers.facebook.com/tools/explorer

2. Configure Explorer:
- Select your app from the dropdown
- Click "Generate Access Token"
- Select required permissions when prompted

3. Get Page Access Token:
- In the explorer, make a GET request to: /me/accounts
- Find your Facebook Page in the response
- Copy the access_token for your page

4. Get Instagram Business Account ID:
- Use the page access token to make a GET request to: /{page-id}?fields=instagram_business_account
- Copy the Instagram Business Account ID from the response

Option B: Using Facebook Login Flow (Recommended for Production)

1. Set Up Facebook Login:
- In your app dashboard, add "Facebook Login" product
- Configure Valid OAuth Redirect URIs

2. Implement OAuth Flow:

   # Example OAuth URL

   oauth_url = f"https://www.facebook.com/v19.0/dialog/oauth?client_id={app_id}&redirect_uri={redirect_uri}&scope=pages_show_list,instagram_basic,instagram_content_publish,instagram_manage_insights"

   

3. Exchange Code for Token:

   # Exchange authorization code for access token

   token_url = f"https://graph.facebook.com/v19.0/oauth/access_token?client_id={app_id}&redirect_uri={redirect_uri}&client_secret={app_secret}&code={auth_code}"

   

Step 6: Get Long-Lived Access Token

Short-lived tokens expire in 1 hour. Convert to long-lived token (60 days):

curl -X GET "https://graph.facebook.com/v19.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}"

Step 7: Set Up Environment Variables

Create a .env file in your project root:

```env