Instagram MCP Server
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
- Instagram Business Account: Must be connected to a Facebook Page
- Facebook Developer Account: Required for API access
- Access Token: Long-lived access token with appropriate permissions
- Python 3.10+: For running the MCP server (required by MCP dependencies)
Required Instagram API Permissions
Standard Access (available immediately):
instagram_basicinstagram_content_publishinstagram_manage_insightsinstagram_manage_commentspages_show_listpages_read_engagementpages_manage_metadatapages_read_user_contentbusiness_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
-
Convert to Business Account (if not already):
- Open Instagram app → Settings → Account → Switch to Professional Account
- Choose "Business" → Select a category → Complete setup
-
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
-
Go to Facebook Developers:
- Visit developers.facebook.com
- Log in with your Facebook account
-
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"
-
Add Instagram Basic Display Product:
- In your app dashboard, click "Add Product"
- Find "Instagram Basic Display" → Click "Set Up"
-
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
- 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
-
Add Instagram Graph API Product:
- In your app dashboard, click "Add Product"
- Find "Instagram Graph API" → Click "Set Up"
-
Configure Permissions:
- Go to Instagram Graph API → Permissions
- Request the following permissions:
instagram_basicinstagram_content_publishinstagram_manage_insightspages_show_listpages_read_engagement
Step 5: Generate Access Token
Option A: Using Facebook Graph API Explorer (Recommended for Testing)
-
Go to Graph API Explorer:
-
Configure Explorer:
- Select your app from the dropdown
- Click "Generate Access Token"
- Select required permissions when prompted
-
Get Page Access Token:
- In the explorer, make a GET request to:
/me/accounts - Find your Facebook Page in the response
- Copy the
access_tokenfor your page
- In the explorer, make a GET request to:
-
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
- Use the page access token to make a GET request to:
Option B: Using Facebook Login Flow (Recommended for Production)
-
Set Up Facebook Login:
- In your app dashboard, add "Facebook Login" product
- Configure Valid OAuth Redirect URIs
-
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" -
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:
# 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
- Never commit credentials to version control
- Use environment variables or secure secret management
- Regularly rotate access tokens
- Monitor token expiration dates
- Use HTTPS only in production
- 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
- Clone the repository:
git clone <repository-url>
cd ig-mcp
- Install dependencies:
pip install -r requirements.txt
- Set up environment variables:
cp .env.example .env
# Edit .env with your Instagram API credentials
- Configure the MCP server:
# Edit config.json with your specific settings
Configuration
Environment Variables (.env)
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id
MCP Client Configuration
Add this to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"instagram": {
"command": "python",
"args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
"env": {
"INSTAGRAM_ACCESS_TOKEN": "your_access_token"
}
}
}
}
Usage Examples
Using with Claude Desktop
- Get Profile Information:
Can you get my Instagram profile information?
- Analyze Recent Posts:
Show me my last 5 Instagram posts and their engagement metrics
- Publish Content:
Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"
Using with Python MCP Client
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# Connect to the Instagram MCP server
server_params = StdioServerParameters(
command="python",
args=["src/instagram_mcp_server.py"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Get profile information
result = await session.call_tool("get_profile_info", {})
print(result)
API Endpoints Covered
Profile Management
- Get business profile information
- Update profile details (future feature)
Media Management
- Retrieve recent posts
- Get specific media details
- Upload and publish new content
- Delete media (future feature)
Analytics & Insights
- Post engagement metrics (likes, comments, shares)
- Account insights (reach, impressions)
- Hashtag performance analysis
Account Management
- List connected Facebook pages
- Switch between business accounts
Rate Limiting & Best Practices
The server implements intelligent rate limiting to comply with Instagram's API limits:
- Profile requests: 200 calls per hour
- Media requests: 200 calls per hour
- Publishing: 25 posts per day
- Insights: 200 calls per hour
Best Practices
- Cache frequently accessed data
- Use batch requests when possible
- Implement exponential backoff for retries
- Monitor rate limit headers
Error Handling
The server provides comprehensive error handling for common scenarios:
- Authentication errors: Invalid or expired tokens
- Permission errors: Missing required permissions
- Rate limiting: Automatic retry with backoff
- Network errors: Connection timeouts and retries
- API errors: Instagram-specific error responses
Security Considerations
- Token Security: Store access tokens securely
- Environment Variables: Never commit tokens to version control
- HTTPS Only: All API calls use HTTPS
- Token Refresh: Implement automatic token refresh
- Audit Logging: Log all API interactions
Development
Project Structure
ig-mcp/
├── src/
│ ├── instagram_mcp_server.py # Main MCP server
│ ├── instagram_client.py # Instagram API client
│ ├── models/ # Data models
│ ├── tools/ # MCP tools implementation
│ ├── resources/ # MCP resources implementation
│ └── prompts/ # MCP prompts implementation
├── tests/ # Unit and integration tests
├── config/ # Configuration files
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # This file
Running Tests
# Run all tests
python -m pytest tests/
# Run with coverage
python -m pytest tests/ --cov=src/
# Run specific test file
python -m pytest tests/test_instagram_client.py
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Troubleshooting
Common Issues
-
"Invalid Access Token"
- Verify token is not expired
- Check token permissions
- Regenerate long-lived token
-
"Rate Limit Exceeded"
- Wait for rate limit reset
- Implement request queuing
- Use batch requests
-
"Permission Denied"
- Verify Instagram Business account setup
- Check Facebook page connection
- Review API permissions
Debug Mode
Enable debug logging by setting:
LOG_LEVEL=DEBUG
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
- 📧 Email: support@example.com
- 🐛 Issues: GitHub Issues
- 📖 Documentation: Wiki
Acknowledgments
- Model Context Protocol by Anthropic
- Instagram Graph API by Meta
- FastMCP for rapid MCP development