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

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_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.

MCP Servers