Skip to content
Back to search

Instagram MCP

SkillWorks with Claude CodeGitHub

23 Instagram Graph API tools — posts, comments, DMs, stories, analytics.

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/mcpware--instagram-mcp/badge.svg)](/listings/mcpware--instagram-mcp)

HTML

<a href="/listings/mcpware--instagram-mcp"><img src="/api/listings/mcpware--instagram-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.

.claude-plugin/plugin.json · Manifest · 7 lines

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

  1. {
  2. "name": "Instagram MCP",
  3. "version": "1.0.4",
  4. "description": "23 Instagram Graph API tools — posts, comments, DMs, stories, analytics.",
  5. "author": "mcpware",
  6. "homepage": "https://github.com/mcpware/instagram-mcp"
  7. }
README.md · README · 576 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. # @mcpware/instagram-mcp
  4. [![npm version](https://img.shields.io/npm/v/@mcpware/instagram-mcp)](https://www.npmjs.com/package/@mcpware/instagram-mcp)
  5. [![npm downloads](https://img.shields.io/npm/dt/@mcpware/instagram-mcp?label=downloads)](https://www.npmjs.com/package/@mcpware/instagram-mcp)
  6. [![license](https://img.shields.io/github/license/mcpware/instagram-mcp)](LICENSE)
  7. [![GitHub stars](https://img.shields.io/github/stars/mcpware/instagram-mcp?style=social)](https://github.com/mcpware/instagram-mcp)
  8. [![GitHub forks](https://img.shields.io/github/forks/mcpware/instagram-mcp?style=social)](https://github.com/mcpware/instagram-mcp/fork)
  9. 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.
  10. ## Features
  11. ### 🔧 Tools (Model-controlled)
  12. - **Get Profile Info**: Retrieve Instagram business profile details
  13. - **Get Media Posts**: Fetch recent posts from an Instagram account
  14. - **Get Media Insights**: Retrieve engagement metrics for specific posts
  15. - **Publish Media**: Upload and publish images/videos to Instagram
  16. - **Get Account Pages**: List Facebook pages connected to the account
  17. - **Get Conversations**: List Instagram DM conversations (requires Advanced Access)
  18. - **Get Conversation Messages**: Read messages from specific conversations (requires Advanced Access)
  19. - **Send DM**: Reply to Instagram direct messages (requires Advanced Access)
  20. ### 📊 Resources (Application-controlled)
  21. - **Profile Data**: Access to profile information including follower counts, bio, etc.
  22. - **Media Feed**: Recent posts with engagement metrics
  23. - **Insights Data**: Detailed analytics for posts and account performance
  24. ### 💬 Prompts (User-controlled)
  25. - **Analyze Engagement**: Pre-built prompt for analyzing post performance
  26. - **Content Strategy**: Template for generating content recommendations
  27. - **Hashtag Analysis**: Prompt for hashtag performance evaluation
  28. ## Prerequisites
  29. 1. **Instagram Business Account**: Must be connected to a Facebook Page
  30. 2. **Facebook Developer Account**: Required for API access
  31. 3. **Access Token**: Long-lived access token with appropriate permissions
  32. 4. **Python 3.10+**: For running the MCP server (required by MCP dependencies)
  33. ### Required Instagram API Permissions
  34. **Standard Access** (available immediately):
  35. - `instagram_basic`
  36. - `instagram_content_publish`
  37. - `instagram_manage_insights`
  38. - `instagram_manage_comments`
  39. - `pages_show_list`
  40. - `pages_read_engagement`
  41. - `pages_manage_metadata`
  42. - `pages_read_user_content`
  43. - `business_management`
  44. **Advanced Access** (requires Meta App Review):
  45. - `instagram_manage_messages` - Required for Direct Messaging features
  46. > ⚠️ **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.
  47. ## 🔑 How to Get Instagram API Credentials
  48. > 📖 **Quick Start**: See [AUTHENTICATION_GUIDE.md](AUTHENTICATION_GUIDE.md) for a 5-minute setup guide!
  49. This section provides a step-by-step guide to obtain the necessary credentials for the Instagram MCP server.
  50. ### Step 1: Set Up Instagram Business Account
  51. 1. **Convert to Business Account** (if not already):
  52. - Open Instagram app → Settings → Account → Switch to Professional Account
  53. - Choose "Business" → Select a category → Complete setup
  54. 2. **Connect to Facebook Page**:
  55. - Go to Instagram Settings → Account → Linked Accounts → Facebook
  56. - Connect to an existing Facebook Page or create a new one
  57. - **Important**: The Facebook Page must be owned by you
  58. ### Step 2: Create Facebook App
  59. 1. **Go to Facebook Developers**:
  60. - Visit [developers.facebook.com](https://developers.facebook.com)
  61. - Log in with your Facebook account
  62. 2. **Create New App**:
  63. - Click "Create App" → Choose "Business" → Click "Next"
  64. - Fill in app details:
  65. - **App Name**: Choose a descriptive name (e.g., "My Instagram MCP Server")
  66. - **App Contact Email**: Your email address
  67. - Click "Create App"
  68. 3. **Add Instagram Basic Display Product**:
  69. - In your app dashboard, click "Add Product"
  70. - Find "Instagram Basic Display" → Click "Set Up"
  71. 4. **Configure Instagram Basic Display**:
  72. - Go to Instagram Basic Display → Basic Display
  73. - Click "Create New App" in the Instagram App section
  74. - Accept the terms and create the app
  75. ### Step 3: Get App Credentials
  76. 1. **Get App ID and Secret**:
  77. - In your Facebook app dashboard, go to Settings → Basic
  78. - Copy your **App ID** and **App Secret**
  79. - **Important**: Keep the App Secret secure and never share it publicly
  80. ### Step 4: Set Up Instagram Business API Access
  81. 1. **Add Instagram Graph API Product**:
  82. - In your app dashboard, click "Add Product"
  83. - Find "Instagram Graph API" → Click "Set Up"
  84. 2. **Configure Permissions**:
  85. - Go to Instagram Graph API → Permissions
  86. - Request the following permissions:
  87. - `instagram_basic`
  88. - `instagram_content_publish`
  89. - `instagram_manage_insights`
  90. - `pages_show_list`
  91. - `pages_read_engagement`
  92. ### Step 5: Generate Access Token
  93. #### Option A: Using Facebook Graph API Explorer (Recommended for Testing)
  94. 1. **Go to Graph API Explorer**:
  95. - Visit [developers.facebook.com/tools/explorer](https://developers.facebook.com/tools/explorer)
  96. 2. **Configure Explorer**:
  97. - Select your app from the dropdown
  98. - Click "Generate Access Token"
  99. - Select required permissions when prompted
  100. 3. **Get Page Access Token**:
  101. - In the explorer, make a GET request to: `/me/accounts`
  102. - Find your Facebook Page in the response
  103. - Copy the `access_token` for your page
  104. 4. **Get Instagram Business Account ID**:
  105. - Use the page access token to make a GET request to: `/{page-id}?fields=instagram_business_account`
  106. - Copy the Instagram Business Account ID from the response
  107. #### Option B: Using Facebook Login Flow (Recommended for Production)
  108. 1. **Set Up Facebook Login**:
  109. - In your app dashboard, add "Facebook Login" product
  110. - Configure Valid OAuth Redirect URIs
  111. 2. **Implement OAuth Flow**:
  112. ```python
  113. # Example OAuth URL
  114. 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"
  115. ```
  116. 3. **Exchange Code for Token**:
  117. ```python
  118. # Exchange authorization code for access token
  119. 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}"
  120. ```
  121. ### Step 6: Get Long-Lived Access Token
  122. Short-lived tokens expire in 1 hour. Convert to long-lived token (60 days):
  123. ```bash
  124. 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}"
  125. ```
  126. ### Step 7: Set Up Environment Variables
  127. Create a `.env` file in your project root:
  128. ```env
  129. # Facebook App Credentials
  130. FACEBOOK_APP_ID=your_app_id_here
  131. FACEBOOK_APP_SECRET=your_app_secret_here
  132. # Instagram Access Token (long-lived)
  133. INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here
  134. # Instagram Business Account ID
  135. INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here
  136. # Optional: API Configuration
  137. INSTAGRAM_API_VERSION=v19.0
  138. RATE_LIMIT_REQUESTS_PER_HOUR=200
  139. CACHE_ENABLED=true
  140. LOG_LEVEL=INFO
  141. ```
  142. ### Step 8: Test Your Setup
  143. Run the validation script to test your credentials:
  144. ```bash
  145. python scripts/setup.py
  146. ```
  147. Or test manually:
  148. ```python
  149. import os
  150. import requests
  151. # Test access token
  152. access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
  153. response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
  154. print(response.json())
  155. ```
  156. ### 🚨 Important Security Notes
  157. 1. **Never commit credentials to version control**
  158. 2. **Use environment variables or secure secret management**
  159. 3. **Regularly rotate access tokens**
  160. 4. **Monitor token expiration dates**
  161. 5. **Use HTTPS only in production**
  162. 6. **Implement proper error handling for expired tokens**
  163. ### 🔄 Token Refresh Strategy
  164. Long-lived tokens expire after 60 days. Implement automatic refresh:
  165. ```python
  166. # Check token validity
  167. def check_token_validity(access_token):
  168. url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
  169. response = requests.get(url)
  170. return response.status_code == 200
  171. # Refresh token before expiration
  172. def refresh_long_lived_token(access_token, app_id, app_secret):
  173. url = f"https://graph.facebook.com/v19.0/oauth/access_token"
  174. params = {
  175. 'grant_type': 'fb_exchange_token',
  176. 'client_id': app_id,
  177. 'client_secret': app_secret,
  178. 'fb_exchange_token': access_token
  179. }
  180. response = requests.get(url, params=params)
  181. return response.json().get('access_token')
  182. ```
  183. ### 📋 Troubleshooting Common Issues
  184. **Error: "Invalid OAuth access token"**
  185. - Check if token has expired
  186. - Verify token has required permissions
  187. - Ensure Instagram account is connected to Facebook Page
  188. **Error: "Instagram account not found"**
  189. - Verify Instagram Business Account ID is correct
  190. - Check if Instagram account is properly linked to Facebook Page
  191. - Ensure account is a Business account, not Personal
  192. **Error: "Insufficient permissions"**
  193. - Review required permissions in Facebook App
  194. - Re-generate access token with correct scopes
  195. - Check if app is in Development vs Live mode
  196. **Rate Limiting Issues**
  197. - Implement exponential backoff
  198. - Cache responses when possible
  199. - Monitor rate limit headers in API responses
  200. ## Installation
  201. 1. **Clone the repository**:
  202. ```bash
  203. git clone <repository-url>
  204. cd ig-mcp
  205. ```
  206. 2. **Install dependencies**:
  207. ```bash
  208. pip install -r requirements.txt
  209. ```
  210. 3. **Set up environment variables**:
  211. ```bash
  212. cp .env.example .env
  213. # Edit .env with your Instagram API credentials
  214. ```
  215. 4. **Configure the MCP server**:
  216. ```bash
  217. # Edit config.json with your specific settings
  218. ```
  219. ## Configuration
  220. ### Environment Variables (.env)
  221. ```env
  222. INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
  223. FACEBOOK_APP_ID=your_facebook_app_id
  224. FACEBOOK_APP_SECRET=your_facebook_app_secret
  225. INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id
  226. ```
  227. ### MCP Client Configuration
  228. Add this to your MCP client configuration (e.g., Claude Desktop):
  229. ```json
  230. {
  231. "mcpServers": {
  232. "instagram": {
  233. "command": "python",
  234. "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
  235. "env": {
  236. "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
  237. }
  238. }
  239. }
  240. }
  241. ```
  242. ## Usage Examples
  243. ### Using with Claude Desktop
  244. 1. **Get Profile Information**:
  245. ```
  246. Can you get my Instagram profile information?
  247. ```
  248. 2. **Analyze Recent Posts**:
  249. ```
  250. Show me my last 5 Instagram posts and their engagement metrics
  251. ```
  252. 3. **Publish Content**:
  253. ```
  254. Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"
  255. ```
  256. ### Using with Python MCP Client
  257. ```python
  258. from mcp import ClientSession, StdioServerParameters
  259. from mcp.client.stdio import stdio_client
  260. # Connect to the Instagram MCP server
  261. server_params = StdioServerParameters(
  262. command="python",
  263. args=["src/instagram_mcp_server.py"]
  264. )
  265. async with stdio_client(server_params) as (read, write):
  266. async with ClientSession(read, write) as session:
  267. await session.initialize()
  268. # Get profile information
  269. result = await session.call_tool("get_profile_info", {})
  270. print(result)
  271. ```
  272. ## API Endpoints Covered
  273. ### Profile Management
  274. - Get business profile information
  275. - Update profile details (future feature)
  276. ### Media Management
  277. - Retrieve recent posts
  278. - Get specific media details
  279. - Upload and publish new content
  280. - Delete media (future feature)
  281. ### Analytics & Insights
  282. - Post engagement metrics (likes, comments, shares)
  283. - Account insights (reach, impressions)
  284. - Hashtag performance analysis
  285. ### Account Management
  286. - List connected Facebook pages
  287. - Switch between business accounts
  288. ## Rate Limiting & Best Practices
  289. The server implements intelligent rate limiting to comply with Instagram's API limits:
  290. - **Profile requests**: 200 calls per hour
  291. - **Media requests**: 200 calls per hour
  292. - **Publishing**: 25 posts per day
  293. - **Insights**: 200 calls per hour
  294. ### Best Practices
  295. 1. Cache frequently accessed data
  296. 2. Use batch requests when possible
  297. 3. Implement exponential backoff for retries
  298. 4. Monitor rate limit headers
  299. ## Error Handling
  300. The server provides comprehensive error handling for common scenarios:
  301. - **Authentication errors**: Invalid or expired tokens
  302. - **Permission errors**: Missing required permissions
  303. - **Rate limiting**: Automatic retry with backoff
  304. - **Network errors**: Connection timeouts and retries
  305. - **API errors**: Instagram-specific error responses
  306. ## Security Considerations
  307. 1. **Token Security**: Store access tokens securely
  308. 2. **Environment Variables**: Never commit tokens to version control
  309. 3. **HTTPS Only**: All API calls use HTTPS
  310. 4. **Token Refresh**: Implement automatic token refresh
  311. 5. **Audit Logging**: Log all API interactions
  312. ## Development
  313. ### Project Structure
  314. ```
  315. ig-mcp/
  316. ├── src/
  317. │ ├── instagram_mcp_server.py # Main MCP server
  318. │ ├── instagram_client.py # Instagram API client
  319. │ ├── models/ # Data models
  320. │ ├── tools/ # MCP tools implementation
  321. │ ├── resources/ # MCP resources implementation
  322. │ └── prompts/ # MCP prompts implementation
  323. ├── tests/ # Unit and integration tests
  324. ├── config/ # Configuration files
  325. ├── requirements.txt # Python dependencies
  326. ├── .env.example # Environment variables template
  327. └── README.md # This file
  328. ```
  329. ### Running Tests
  330. ```bash
  331. # Run all tests
  332. python -m pytest tests/
  333. # Run with coverage
  334. python -m pytest tests/ --cov=src/
  335. # Run specific test file
  336. python -m pytest tests/test_instagram_client.py
  337. ```
  338. ### Contributing
  339. 1. Fork the repository
  340. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  341. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  342. 4. Push to the branch (`git push origin feature/amazing-feature`)
  343. 5. Open a Pull Request
  344. ## Troubleshooting
  345. ### Common Issues
  346. 1. **"Invalid Access Token"**
  347. - Verify token is not expired
  348. - Check token permissions
  349. - Regenerate long-lived token
  350. 2. **"Rate Limit Exceeded"**
  351. - Wait for rate limit reset
  352. - Implement request queuing
  353. - Use batch requests
  354. 3. **"Permission Denied"**
  355. - Verify Instagram Business account setup
  356. - Check Facebook page connection
  357. - Review API permissions
  358. ### Debug Mode
  359. Enable debug logging by setting:
  360. ```env
  361. LOG_LEVEL=DEBUG
  362. ```
  363. ### Troubleshooting
  364. | Problem | Cause | Fix |
  365. |---------|-------|-----|
  366. | `me/accounts` returns empty `[]` | IG not connected to a Facebook Page, or you're not Page admin | Do Step 1 |
  367. | Graph API Explorer says "No configuration available" | Permissions not added to app | Do Step 3 |
  368. | "Generate Access Token" is disabled | Need to select "Get User Access Token" first | Click "Get Token" dropdown |
  369. | App name rejected (contains "IG", "Insta", etc.) | Meta blocks trademarked words | Use a generic name |
  370. | Token expired | Short-lived tokens last 1 hour | Do Step 6 for 60-day token |
  371. | `(#10) To use Instagram Graph API...` | IG account is Personal, not Business | Switch to Business/Creator in IG settings |
  372. ## Environment Variables
  373. | Variable | Required | Default | Description |
  374. |----------|----------|---------|-------------|
  375. | `INSTAGRAM_ACCESS_TOKEN` | Yes | — | Meta long-lived access token |
  376. | `INSTAGRAM_ACCOUNT_ID` | Yes | — | Instagram business account ID |
  377. | `INSTAGRAM_API_VERSION` | No | `v19.0` | Graph API version |
  378. ## Tools (23)
  379. ### Profile & Account
  380. | Tool | Description |
  381. |------|-------------|
  382. | `get_profile_info` | Get profile info (bio, followers, media count) |
  383. | `get_account_pages` | List connected Facebook pages |
  384. | `get_account_insights` | Account-level analytics (reach, profile views) |
  385. | `validate_access_token` | Check if token is valid |
  386. ### Media & Publishing
  387. | Tool | Description |
  388. |------|-------------|
  389. | `get_media_posts` | Get recent posts with engagement metrics |
  390. | `get_media_insights` | Detailed analytics for a specific post |
  391. | `publish_media` | Publish image or video |
  392. | `publish_carousel` | Publish carousel (2-10 images/videos) |
  393. | `publish_reel` | Publish a Reel |
  394. | `get_content_publishing_limit` | Check daily publishing quota |
  395. ### Comments
  396. | Tool | Description |
  397. |------|-------------|
  398. | `get_comments` | Get comments on a post |
  399. | `post_comment` | Post a comment |
  400. | `reply_to_comment` | Reply to a comment |
  401. | `delete_comment` | Delete a comment |
  402. | `hide_comment` | Hide/unhide a comment |
  403. ### Direct Messages
  404. | Tool | Description |
  405. |------|-------------|
  406. | `get_conversations` | List DM conversations |
  407. | `get_conversation_messages` | Read messages in a conversation |
  408. | `send_dm` | Send a direct message |
  409. ### Discovery & Content
  410. | Tool | Description |
  411. |------|-------------|
  412. | `search_hashtag` | Search for a hashtag ID |
  413. | `get_hashtag_media` | Get top/recent media for a hashtag |
  414. | `get_stories` | Get current active stories |
  415. | `get_mentions` | Get posts you're tagged in |
  416. | `business_discovery` | Look up another business account |
  417. ## Limitations
  418. These are Instagram Graph API limitations, not this tool's:
  419. - **Business/Creator accounts only** — personal accounts are not supported
  420. - **Long-lived tokens expire after 60 days** — refresh before expiry
  421. - **200 API calls per hour** rate limit
  422. - **25 posts per day** publishing limit
  423. - **DMs require Advanced Access** — Meta app review required
  424. - **Hashtag search**: 30 unique hashtags per 7 days
  425. ## Credits
  426. TypeScript rewrite of [jlbadano/ig-mcp](https://github.com/jlbadano/ig-mcp) (Python).
  427. ## More from @mcpware
  428. | Project | What it does | Install |
  429. |---------|---|---|
  430. | **[Claude Code Organizer](https://github.com/mcpware/claude-code-organizer)** | Visual dashboard for Claude Code memories, skills, MCP servers, hooks | `npx @mcpware/claude-code-organizer` |
  431. | **[UI Annotator](https://github.com/mcpware/ui-annotator-mcp)** | Hover labels on any web page — AI references elements by name | `npx @mcpware/ui-annotator` |
  432. | **[Pagecast](https://github.com/mcpware/pagecast)** | Record browser sessions as GIF or video via MCP | `npx @mcpware/pagecast` |
  433. | **[LogoLoom](https://github.com/mcpware/logoloom)** | AI logo design → SVG → full brand kit export | `npx @mcpware/logoloom` |
  434. ## License
  435. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  436. ## Support
  437. - 📧 Email: support@example.com
  438. - 🐛 Issues: [GitHub Issues](https://github.com/jlbadano/ig-mcp/issues)
  439. - 📖 Documentation: [Wiki](https://github.com/jlbadano/ig-mcp/wiki)
  440. ## Acknowledgments
  441. - [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
  442. - [Instagram Graph API](https://developers.facebook.com/docs/instagram-api/) by Meta
  443. - [FastMCP](https://github.com/jlowin/fastmcp) for rapid MCP development

Version history

  • v1.0.410/30/2026

Ratings and comments

Sign in to rate this skill.

Sign in

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