Instagram MCP Server (Rust)
A Model Context Protocol server for the Instagram Graph API, built with Rust. Provides AI applications with programmatic access to Instagram Business accounts via MCP tools, resources, and prompts.
Features
🔧 Tools (Model-controlled)
📊 Resources (Application-controlled)
instagram://profile/{account_id}— profile infoinstagram://media/{account_id}— recent postsinstagram://insights/{media_id}— post analyticsinstagram://account-insights/{account_id}— account analytics
💬 Prompts (User-controlled)
- Analyze Engagement — pre-built prompt for post performance analysis
- Content Strategy — template for 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 token with appropriate permissions
- Rust toolchain — edition 2021, minimum supported version in
Cargo.toml
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 DM features
⚠️ See INSTAGRAM_DM_SETUP.md for the App Review process.
🔑 Getting Credentials
📖 See AUTHENTICATION_GUIDE.md for a 5-minute setup guide.
Environment Variables
Create a .env file in the project root:
INSTAGRAM_ACCESS_TOKEN=your_long_lived_token
FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_ig_business_id
The server also symlinks ../.env for development — a .env at the parent level works too.
🚀 Installation & Usage
# Build
cargo build --release
# Run (stdio transport — connects to any MCP host)
cargo run
Output goes to stderr (JSON-formatted tracing). Stdout is reserved for the MCP protocol transport.
MCP Configuration
Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"instagram": {
"command": "/path/to/ig-mcp-rust/target/release/ig-mcp",
"env": {
"INSTAGRAM_ACCESS_TOKEN": "your_access_token",
"FACEBOOK_APP_ID": "your_app_id",
"FACEBOOK_APP_SECRET": "your_app_secret"
}
}
}
}
Other MCP Hosts
Point the host at the compiled binary with stdio transport. All configuration is via environment variables.
Usage Examples
Once connected, you can ask your AI assistant:
- "Show me my Instagram profile and follower count"
- "What were my last 5 posts and how did they perform?"
- "Upload this image with the caption 'Hello world!'"
- "Give me a content strategy for the next week"
Project Structure
ig-mcp-rust/
├── src/
│ ├── main.rs # Entrypoint, config loading, token validation
│ ├── lib.rs # Module re-exports
│ ├── client.rs # InstagramClient — HTTP + rate limiting + cache
│ ├── server.rs # InstagramMcpServer — MCP handler
│ ├── models.rs # Request/response types & params
│ ├── config.rs # Env-based configuration
│ └── error.rs # Unified AppError enum
├── Cargo.toml
├── AGENTS.md
├── AUTHENTICATION_GUIDE.md
├── INSTAGRAM_DM_SETUP.md
└── README.md
Architecture Notes
- Rate limiting is enforced per-hour with a
governortoken bucket (burst = quota). - Response caching uses
moka(async, TTL-based). Only GET responses are cached; mutations bypass cache. - Image validation checks aspect ratios before publishing (stories: 9:16, carousel albums: 1:1 or 1.91:1).
- DM traffic routes through
https://graph.facebook.com/v22.0(separate from the main API). - Error wrapping on DM failures appends a helpful note about Advanced Access requirements.
API Endpoints Covered
- Profile management (read + update)
- Media retrieval and publishing (posts + stories)
- Engagement analytics (post-level + account-level)
- DM conversation listing, reading, and sending
- Facebook page discovery
Rate Limits & Best Practices
- Default: 200 requests/hour (configurable via
RATE_LIMIT_REQUESTS_PER_HOUR) - Response caching reduces duplicate API calls (5 min TTL by default)
- Use the
instagram://resource URIs for quick data access without tool calls
Error Handling
- AppError enum covers API errors, HTTP failures, rate limiting, config issues, and image validation.
- Startup validates the access token and exits immediately on failure.
- All tool results are wrapped in
McpToolResult { success, data, error, metadata }.
Development
cargo build
cargo check # Fast lint-style verification
cargo run # Run with .env config
Contributions welcome — open an issue or PR.
License
MIT — see LICENSE.