Instagram MCP — 23 tools for Instagram Graph API: posts, DMs, stories, reels, analytics.
Instagram MCP — 23 tools for Instagram Graph API: posts, DMs, stories, reels, analytics.
Valid MCP server (3 strong, 1 medium validity signals). 11 known CVEs in dependencies (1 critical, 6 high severity) Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (6/6 approved).
5 files analyzed · 12 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Unverified package source
We couldn't verify that the installable package matches the reviewed source code. Proceed with caution.
Set these up before or after installing:
Environment variable: INSTAGRAM_ACCESS_TOKEN
Environment variable: INSTAGRAM_ACCOUNT_ID
Environment variable: INSTAGRAM_API_VERSION
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-mcpware-instagram-mcp": {
"env": {
"INSTAGRAM_ACCOUNT_ID": "your-instagram-account-id-here",
"INSTAGRAM_API_VERSION": "your-instagram-api-version-here",
"INSTAGRAM_ACCESS_TOKEN": "your-instagram-access-token-here"
},
"args": [
"-y",
"@mcpware/instagram-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
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.
Standard Access (available immediately):
instagram_basicinstagram_content_publishinstagram_manage_insightsinstagram_manage_commentspages_show_listpages_read_engagementpages_manage_metadatapages_read_user_contentbusiness_managementAdvanced 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.
📖 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.
Convert to Business Account (if not already):
Connect to Facebook Page:
Go to Facebook Developers:
Create New App:
Add Instagram Basic Display Product:
Configure Instagram Basic Display:
Add Instagram Graph API Product:
Configure Permissions:
instagram_basicinstagram_content_publishinstagram_manage_insightspages_show_listpages_read_engagementGo to Graph API Explorer:
Configure Explorer:
Get Page Access Token:
/me/accountsaccess_token for your pageGet Instagram Business Account ID:
/{page-id}?fields=instagram_business_accountSet Up Facebook Login:
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}"
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}"
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
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())
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')
Error: "Invalid OAuth access token"
Error: "Instagram account not found"
Error: "Insufficient permissions"
Rate Limiting Issues
git clone <repository-url>
cd ig-mcp
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your Instagram API credentials
# Edit config.json with your specific settings
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
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"
}
}
}
}
Can you get my Instagram profile information?
Show me my last 5 Instagram posts and their engagement metrics
Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"
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)
The server implements intelligent rate limiting to comply with Instagram's API limits:
The server provides comprehensive error handling for common scenarios:
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
# 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
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)"Invalid Access Token"
"Rate Limit Exceeded"
"Permission Denied"
Enable debug logging by setting:
LOG_LEVEL=DEBUG
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Tool | Description |
|---|---|
get_conversations | List DM conversations |
get_conversation_messages | Read messages in a conversation |
send_dm | Send a direct message |
| 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 |
These are Instagram Graph API limitations, not this tool's:
TypeScript rewrite of jlbadano/ig-mcp (Python).
| Project | What it does | Install |
|---|---|---|
| Claude Code Organizer | Visual dashboard for Claude Code memories, skills, MCP servers, hooks | npx @mcpware/claude-code-organizer |
| UI Annotator | Hover labels on any web page — AI references elements by name | npx @mcpware/ui-annotator |
| Pagecast | Record browser sessions as GIF or video via MCP | npx @mcpware/pagecast |
| LogoLoom | AI logo design → SVG → full brand kit export | npx @mcpware/logoloom |
This project is licensed under the MIT License - see the LICENSE file for details.
Be the first to review this server!
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
by Taylorwilsdon · Productivity
Control Gmail, Calendar, Docs, Sheets, Drive, and more from your AI