Skip to content
Back to search

ig-mcp

A production-ready Model Context Protocol (MCP) server that enables AI applications to seamlessly interact with Instagram Business accounts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jlbadano--ig-mcp/badge.svg)](/listings/jlbadano--ig-mcp)

HTML

<a href="/listings/jlbadano--ig-mcp"><img src="/api/listings/jlbadano--ig-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 483 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/7bde8131-7019-405f-89d1-cef574a8129a)
  2. [![MSeeP.ai Security Assessment Badge](https://mseep.net/pr/jlbadano-ig-mcp-badge.png)](https://mseep.ai/app/jlbadano-ig-mcp)
  3. # Instagram MCP Server
  4. 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.
  5. ## Features
  6. ### 🔧 Tools (Model-controlled)
  7. - **Get Profile Info**: Retrieve Instagram business profile details
  8. - **Get Media Posts**: Fetch recent posts from an Instagram account
  9. - **Get Media Insights**: Retrieve engagement metrics for specific posts
  10. - **Publish Media**: Upload and publish images/videos to Instagram
  11. - **Get Account Pages**: List Facebook pages connected to the account
  12. - **Get Conversations**: List Instagram DM conversations (requires Advanced Access)
  13. - **Get Conversation Messages**: Read messages from specific conversations (requires Advanced Access)
  14. - **Send DM**: Reply to Instagram direct messages (requires Advanced Access)
  15. ### 📊 Resources (Application-controlled)
  16. - **Profile Data**: Access to profile information including follower counts, bio, etc.
  17. - **Media Feed**: Recent posts with engagement metrics
  18. - **Insights Data**: Detailed analytics for posts and account performance
  19. ### 💬 Prompts (User-controlled)
  20. - **Analyze Engagement**: Pre-built prompt for analyzing post performance
  21. - **Content Strategy**: Template for generating content recommendations
  22. - **Hashtag Analysis**: Prompt for hashtag performance evaluation
  23. ## Prerequisites
  24. 1. **Instagram Business Account**: Must be connected to a Facebook Page
  25. 2. **Facebook Developer Account**: Required for API access
  26. 3. **Access Token**: Long-lived access token with appropriate permissions
  27. 4. **Python 3.10+**: For running the MCP server (required by MCP dependencies)
  28. ### Required Instagram API Permissions
  29. **Standard Access** (available immediately):
  30. - `instagram_basic`
  31. - `instagram_content_publish`
  32. - `instagram_manage_insights`
  33. - `instagram_manage_comments`
  34. - `pages_show_list`
  35. - `pages_read_engagement`
  36. - `pages_manage_metadata`
  37. - `pages_read_user_content`
  38. - `business_management`
  39. **Advanced Access** (requires Meta App Review):
  40. - `instagram_manage_messages` - Required for Direct Messaging features
  41. > ⚠️ **Instagram DM Features**: Reading and sending Instagram direct messages requires Advanced Access approval from Meta. See [INSTAGRAM_DM_SETUP.md](INSTAGRAM_DM_SETUP.md) for the App Review process.
  42. ## 🔑 How to Get Instagram API Credentials
  43. > 📖 **Quick Start**: See [AUTHENTICATION_GUIDE.md](AUTHENTICATION_GUIDE.md) for a 5-minute setup guide!
  44. This section provides a step-by-step guide to obtain the necessary credentials for the Instagram MCP server.
  45. ### Step 1: Set Up Instagram Business Account
  46. 1. **Convert to Business Account** (if not already):
  47. - Open Instagram app → Settings → Account → Switch to Professional Account
  48. - Choose "Business" → Select a category → Complete setup
  49. 2. **Connect to Facebook Page**:
  50. - Go to Instagram Settings → Account → Linked Accounts → Facebook
  51. - Connect to an existing Facebook Page or create a new one
  52. - **Important**: The Facebook Page must be owned by you
  53. ### Step 2: Create Facebook App
  54. 1. **Go to Facebook Developers**:
  55. - Visit [developers.facebook.com](https://developers.facebook.com)
  56. - Log in with your Facebook account
  57. 2. **Create New App**:
  58. - Click "Create App" → Choose "Business" → Click "Next"
  59. - Fill in app details:
  60. - **App Name**: Choose a descriptive name (e.g., "My Instagram MCP Server")
  61. - **App Contact Email**: Your email address
  62. - Click "Create App"
  63. 3. **Add Instagram Basic Display Product**:
  64. - In your app dashboard, click "Add Product"
  65. - Find "Instagram Basic Display" → Click "Set Up"
  66. 4. **Configure Instagram Basic Display**:
  67. - Go to Instagram Basic Display → Basic Display
  68. - Click "Create New App" in the Instagram App section
  69. - Accept the terms and create the app
  70. ### Step 3: Get App Credentials
  71. 1. **Get App ID and Secret**:
  72. - In your Facebook app dashboard, go to Settings → Basic
  73. - Copy your **App ID** and **App Secret**
  74. - **Important**: Keep the App Secret secure and never share it publicly
  75. ### Step 4: Set Up Instagram Business API Access
  76. 1. **Add Instagram Graph API Product**:
  77. - In your app dashboard, click "Add Product"
  78. - Find "Instagram Graph API" → Click "Set Up"
  79. 2. **Configure Permissions**:
  80. - Go to Instagram Graph API → Permissions
  81. - Request the following permissions:
  82. - `instagram_basic`
  83. - `instagram_content_publish`
  84. - `instagram_manage_insights`
  85. - `pages_show_list`
  86. - `pages_read_engagement`
  87. ### Step 5: Generate Access Token
  88. #### Option A: Using Facebook Graph API Explorer (Recommended for Testing)
  89. 1. **Go to Graph API Explorer**:
  90. - Visit [developers.facebook.com/tools/explorer](https://developers.facebook.com/tools/explorer)
  91. 2. **Configure Explorer**:
  92. - Select your app from the dropdown
  93. - Click "Generate Access Token"
  94. - Select required permissions when prompted
  95. 3. **Get Page Access Token**:
  96. - In the explorer, make a GET request to: `/me/accounts`
  97. - Find your Facebook Page in the response
  98. - Copy the `access_token` for your page
  99. 4. **Get Instagram Business Account ID**:
  100. - Use the page access token to make a GET request to: `/{page-id}?fields=instagram_business_account`
  101. - Copy the Instagram Business Account ID from the response
  102. #### Option B: Using Facebook Login Flow (Recommended for Production)
  103. 1. **Set Up Facebook Login**:
  104. - In your app dashboard, add "Facebook Login" product
  105. - Configure Valid OAuth Redirect URIs
  106. 2. **Implement OAuth Flow**:
  107. ```python
  108. # Example OAuth URL
  109. 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"
  110. ```
  111. 3. **Exchange Code for Token**:
  112. ```python
  113. # Exchange authorization code for access token
  114. 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}"
  115. ```
  116. ### Step 6: Get Long-Lived Access Token
  117. Short-lived tokens expire in 1 hour. Convert to long-lived token (60 days):
  118. ```bash
  119. 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}"
  120. ```
  121. ### Step 7: Set Up Environment Variables
  122. Create a `.env` file in your project root:
  123. ```env
  124. # Facebook App Credentials
  125. FACEBOOK_APP_ID=your_app_id_here
  126. FACEBOOK_APP_SECRET=your_app_secret_here
  127. # Instagram Access Token (long-lived)
  128. INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here
  129. # Instagram Business Account ID
  130. INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here
  131. # Optional: API Configuration
  132. INSTAGRAM_API_VERSION=v19.0
  133. RATE_LIMIT_REQUESTS_PER_HOUR=200
  134. CACHE_ENABLED=true
  135. LOG_LEVEL=INFO
  136. ```
  137. ### Step 8: Test Your Setup
  138. Run the validation script to test your credentials:
  139. ```bash
  140. python scripts/setup.py
  141. ```
  142. Or test manually:
  143. ```python
  144. import os
  145. import requests
  146. # Test access token
  147. access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
  148. response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
  149. print(response.json())
  150. ```
  151. ### 🚨 Important Security Notes
  152. 1. **Never commit credentials to version control**
  153. 2. **Use environment variables or secure secret management**
  154. 3. **Regularly rotate access tokens**
  155. 4. **Monitor token expiration dates**
  156. 5. **Use HTTPS only in production**
  157. 6. **Implement proper error handling for expired tokens**
  158. ### 🔄 Token Refresh Strategy
  159. Long-lived tokens expire after 60 days. Implement automatic refresh:
  160. ```python
  161. # Check token validity
  162. def check_token_validity(access_token):
  163. url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
  164. response = requests.get(url)
  165. return response.status_code == 200
  166. # Refresh token before expiration
  167. def refresh_long_lived_token(access_token, app_id, app_secret):
  168. url = f"https://graph.facebook.com/v19.0/oauth/access_token"
  169. params = {
  170. 'grant_type': 'fb_exchange_token',
  171. 'client_id': app_id,
  172. 'client_secret': app_secret,
  173. 'fb_exchange_token': access_token
  174. }
  175. response = requests.get(url, params=params)
  176. return response.json().get('access_token')
  177. ```
  178. ### 📋 Troubleshooting Common Issues
  179. **Error: "Invalid OAuth access token"**
  180. - Check if token has expired
  181. - Verify token has required permissions
  182. - Ensure Instagram account is connected to Facebook Page
  183. **Error: "Instagram account not found"**
  184. - Verify Instagram Business Account ID is correct
  185. - Check if Instagram account is properly linked to Facebook Page
  186. - Ensure account is a Business account, not Personal
  187. **Error: "Insufficient permissions"**
  188. - Review required permissions in Facebook App
  189. - Re-generate access token with correct scopes
  190. - Check if app is in Development vs Live mode
  191. **Rate Limiting Issues**
  192. - Implement exponential backoff
  193. - Cache responses when possible
  194. - Monitor rate limit headers in API responses
  195. ## Installation
  196. 1. **Clone the repository**:
  197. ```bash
  198. git clone <repository-url>
  199. cd ig-mcp
  200. ```
  201. 2. **Install dependencies**:
  202. ```bash
  203. pip install -r requirements.txt
  204. ```
  205. 3. **Set up environment variables**:
  206. ```bash
  207. cp .env.example .env
  208. # Edit .env with your Instagram API credentials
  209. ```
  210. 4. **Configure the MCP server**:
  211. ```bash
  212. # Edit config.json with your specific settings
  213. ```
  214. ## Configuration
  215. ### Environment Variables (.env)
  216. ```env
  217. INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
  218. FACEBOOK_APP_ID=your_facebook_app_id
  219. FACEBOOK_APP_SECRET=your_facebook_app_secret
  220. INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id
  221. ```
  222. ### MCP Client Configuration
  223. Add this to your MCP client configuration (e.g., Claude Desktop):
  224. ```json
  225. {
  226. "mcpServers": {
  227. "instagram": {
  228. "command": "python",
  229. "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
  230. "env": {
  231. "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
  232. }
  233. }
  234. }
  235. }
  236. ```
  237. ## Usage Examples
  238. ### Using with Claude Desktop
  239. 1. **Get Profile Information**:
  240. ```
  241. Can you get my Instagram profile information?
  242. ```
  243. 2. **Analyze Recent Posts**:
  244. ```
  245. Show me my last 5 Instagram posts and their engagement metrics
  246. ```
  247. 3. **Publish Content**:
  248. ```
  249. Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"
  250. ```
  251. ### Using with Python MCP Client
  252. ```python
  253. from mcp import ClientSession, StdioServerParameters
  254. from mcp.client.stdio import stdio_client
  255. # Connect to the Instagram MCP server
  256. server_params = StdioServerParameters(
  257. command="python",
  258. args=["src/instagram_mcp_server.py"]
  259. )
  260. async with stdio_client(server_params) as (read, write):
  261. async with ClientSession(read, write) as session:
  262. await session.initialize()
  263. # Get profile information
  264. result = await session.call_tool("get_profile_info", {})
  265. print(result)
  266. ```
  267. ## API Endpoints Covered
  268. ### Profile Management
  269. - Get business profile information
  270. - Update profile details (future feature)
  271. ### Media Management
  272. - Retrieve recent posts
  273. - Get specific media details
  274. - Upload and publish new content
  275. - Delete media (future feature)
  276. ### Analytics & Insights
  277. - Post engagement metrics (likes, comments, shares)
  278. - Account insights (reach, impressions)
  279. - Hashtag performance analysis
  280. ### Account Management
  281. - List connected Facebook pages
  282. - Switch between business accounts
  283. ## Rate Limiting & Best Practices
  284. The server implements intelligent rate limiting to comply with Instagram's API limits:
  285. - **Profile requests**: 200 calls per hour
  286. - **Media requests**: 200 calls per hour
  287. - **Publishing**: 25 posts per day
  288. - **Insights**: 200 calls per hour
  289. ### Best Practices
  290. 1. Cache frequently accessed data
  291. 2. Use batch requests when possible
  292. 3. Implement exponential backoff for retries
  293. 4. Monitor rate limit headers
  294. ## Error Handling
  295. The server provides comprehensive error handling for common scenarios:
  296. - **Authentication errors**: Invalid or expired tokens
  297. - **Permission errors**: Missing required permissions
  298. - **Rate limiting**: Automatic retry with backoff
  299. - **Network errors**: Connection timeouts and retries
  300. - **API errors**: Instagram-specific error responses
  301. ## Security Considerations
  302. 1. **Token Security**: Store access tokens securely
  303. 2. **Environment Variables**: Never commit tokens to version control
  304. 3. **HTTPS Only**: All API calls use HTTPS
  305. 4. **Token Refresh**: Implement automatic token refresh
  306. 5. **Audit Logging**: Log all API interactions
  307. ## Development
  308. ### Project Structure
  309. ```
  310. ig-mcp/
  311. ├── src/
  312. │ ├── instagram_mcp_server.py # Main MCP server
  313. │ ├── instagram_client.py # Instagram API client
  314. │ ├── models/ # Data models
  315. │ ├── tools/ # MCP tools implementation
  316. │ ├── resources/ # MCP resources implementation
  317. │ └── prompts/ # MCP prompts implementation
  318. ├── tests/ # Unit and integration tests
  319. ├── config/ # Configuration files
  320. ├── requirements.txt # Python dependencies
  321. ├── .env.example # Environment variables template
  322. └── README.md # This file
  323. ```
  324. ### Running Tests
  325. ```bash
  326. # Run all tests
  327. python -m pytest tests/
  328. # Run with coverage
  329. python -m pytest tests/ --cov=src/
  330. # Run specific test file
  331. python -m pytest tests/test_instagram_client.py
  332. ```
  333. ### Contributing
  334. 1. Fork the repository
  335. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  336. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  337. 4. Push to the branch (`git push origin feature/amazing-feature`)
  338. 5. Open a Pull Request
  339. ## Troubleshooting
  340. ### Common Issues
  341. 1. **"Invalid Access Token"**
  342. - Verify token is not expired
  343. - Check token permissions
  344. - Regenerate long-lived token
  345. 2. **"Rate Limit Exceeded"**
  346. - Wait for rate limit reset
  347. - Implement request queuing
  348. - Use batch requests
  349. 3. **"Permission Denied"**
  350. - Verify Instagram Business account setup
  351. - Check Facebook page connection
  352. - Review API permissions
  353. ### Debug Mode
  354. Enable debug logging by setting:
  355. ```env
  356. LOG_LEVEL=DEBUG
  357. ```
  358. ## License
  359. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  360. ## Support
  361. - 📧 Email: support@example.com
  362. - 🐛 Issues: [GitHub Issues](https://github.com/jlbadano/ig-mcp/issues)
  363. - 📖 Documentation: [Wiki](https://github.com/jlbadano/ig-mcp/wiki)
  364. ## Acknowledgments
  365. - [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
  366. - [Instagram Graph API](https://developers.facebook.com/docs/instagram-api/) by Meta
  367. - [FastMCP](https://github.com/jlowin/fastmcp) for rapid MCP development

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.