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

   python

   Copy

   # 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:

   python

   Copy

   # 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:

# Facebook App Credentials
FACEBOOK_APP_ID=your_app_id_here
FACEBOOK_APP_SECRET=your_app_secret_here

# Instagram Access Token (long-lived)
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here

# Instagram Business Account ID
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here

# Optional: API Configuration
INSTAGRAM_API_VERSION=v19.0
RATE_LIMIT_REQUESTS_PER_HOUR=200
CACHE_ENABLED=true
LOG_LEVEL=INFO

Step 8: Test Your Setup

Run the validation script to test your credentials:

python scripts/setup.py

Or test manually:

import os
import requests

# Test access token
access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
print(response.json())

🚨 Important Security Notes

1. Never commit credentials to version control
2. Use environment variables or secure secret management
3. Regularly rotate access tokens
4. Monitor token expiration dates
5. Use HTTPS only in production
6. Implement proper error handling for expired tokens

🔄 Token Refresh Strategy

Long-lived tokens expire after 60 days. Implement automatic refresh:

# Check token validity
def check_token_validity(access_token):
    url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
    response = requests.get(url)
    return response.status_code == 200

# Refresh token before expiration
def refresh_long_lived_token(access_token, app_id, app_secret):
    url = f"https://graph.facebook.com/v19.0/oauth/access_token"
    params = {
        'grant_type': 'fb_exchange_token',
        'client_id': app_id,
        'client_secret': app_secret,
        'fb_exchange_token': access_token
    }
    response = requests.get(url, params=params)
    return response.json().get('access_token')

📋 Troubleshooting Common Issues

Error: "Invalid OAuth access token"

• Check if token has expired
• Verify token has required permissions
• Ensure Instagram account is connected to Facebook Page

Error: "Instagram account not found"

• Verify Instagram Business Account ID is correct
• Check if Instagram account is properly linked to Facebook Page
• Ensure account is a Business account, not Personal

Error: "Insufficient permissions"

• Review required permissions in Facebook App
• Re-generate access token with correct scopes
• Check if app is in Development vs Live mode

Rate Limiting Issues

• Implement exponential backoff
• Cache responses when possible
• Monitor rate limit headers in API responses

Installation

1. Clone the repository:

git clone <repository-url>
cd ig-mcp