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)

| Tool | Description | |------|-------------| | get_profile_info | Retrieve Instagram business profile details | | get_media_posts | Fetch recent posts with engagement metrics | | get_media_insights | Get detailed analytics for a specific post | | publish_media | Upload and publish images/videos | | get_account_insights | Account-level analytics (reach, impressions, etc.) | | get_facebook_pages | List connected Facebook pages | | get_conversations | List DM conversations (requires Advanced Access) | | get_conversation_messages | Read messages from a conversation (Advanced Access) | | send_dm | Reply to Instagram DMs (Advanced Access) | | publish_story | Publish an Instagram story | | update_profile | Update your Instagram profile (website/bio) |

📊 Resources (Application-controlled)

• instagram://profile/{account_id} — profile info
• instagram://media/{account_id} — recent posts
• instagram://insights/{media_id} — post analytics
• instagram://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

1. Instagram Business Account — must be connected to a Facebook Page
2. Facebook Developer Account — required for API access
3. Access Token — long-lived token with appropriate permissions
4. Rust toolchain — edition 2021, minimum supported version in Cargo.toml

Required Instagram API Permissions

Standard Access (available immediately):

• instagram_basic
• instagram_content_publish
• instagram_manage_insights
• instagram_manage_comments
• pages_show_list
• pages_read_engagement
• pages_manage_metadata
• pages_read_user_content
• business_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

| Variable | Required | Default | Description | |---|---|---|---| | INSTAGRAM_ACCESS_TOKEN | Yes | — | Long-lived Instagram access token | | FACEBOOK_APP_ID | Yes | — | Facebook app ID | | FACEBOOK_APP_SECRET | Yes | — | Facebook app secret | | INSTAGRAM_BUSINESS_ACCOUNT_ID | No | — | Instagram business account ID | | INSTAGRAM_API_VERSION | No | v19.0 | Instagram Graph API version | | INSTAGRAM_API_BASE_URL | No | https://graph.facebook.com | API base URL | | RATE_LIMIT_REQUESTS_PER_HOUR | No | 200 | Max requests per hour | | CACHE_ENABLED | No | true | Enable response caching | | CACHE_TTL_SECONDS | No | 300 | Cache TTL (seconds) | | MCP_SERVER_NAME | No | instagram-mcp-server | Server name for MCP | | MCP_SERVER_VERSION | No | 1.0.0 | Server version |

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 governor token 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.