instagram-mcp

Production-grade MCP server for Instagram. 79 tools — 30 anonymous (no credentials), 48 authenticated, 1 auto-mode. Built on curl_cffi with Chrome TLS impersonation, adaptive rate limiting, smart caching, multi-account pool, and challenge/2FA resolver.

Works with Claude Desktop, Claude Code, and any MCP-compatible AI client.

Auth Tiers

Installation

pip install instamcp
instagram-mcp

Or from source:

git clone https://github.com/mpython77/instagram-mcp.git
cd instagram-mcp
pip install -e .
instagram-mcp

With uv:

uv sync && uv run --quiet instagram-mcp

Cookie Setup

1. Log in to Instagram in your browser.
2. Install Cookie-Editor and navigate to instagram.com.
3. Export cookies as JSON.
4. Save as cookies.json in the project root, or set INSTAGRAM_MCP_COOKIES=/path/to/file.

Use a dedicated account — not your personal account. Sessions expire; refresh cookies.json if you get 401 errors.

MCP Config

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "instagram": {
      "command": "instagram-mcp",
      "env": {
        "INSTAGRAM_MCP_COOKIES": "/absolute/path/to/cookies.json"
      }
    }
  }
}

With uv:

{
  "mcpServers": {
    "instagram": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/instagram-mcp", "instagram-mcp"],
      "env": {
        "INSTAGRAM_MCP_COOKIES": "/absolute/path/to/cookies.json"
      }
    }
  }
}

Claude Code

claude mcp add instagram instagram-mcp --env INSTAGRAM_MCP_COOKIES=/path/to/cookies.json

Docker

docker run -d \
  -e INSTAGRAM_MCP_COOKIES=/data/cookies.json \
  -v /path/to/cookies.json:/data/cookies.json:ro \
  -p 8000:8000 \
  ghcr.io/mpython77/instagram-mcp:latest

Environment Variables

Tools

🌐 Profile & Feed

🌐 Analysis

🌐 Content

🌐/🔐 Hashtag & Discovery

🌐 Threads

🔐 Authenticated Feed & Activity

🔐 Discovery

🔐 Social Graph

🔐 Media

🔐 Interactions

🔐 DM

🔐 Upload & Download

🔐 Broadcast & Automation

🌐 Batch & Server

Limitations

• Private accounts: Feed, posts, stories, and highlights are not accessible without following the account.
• Follower pagination: Restricted to ~50 for other accounts; unlimited only for your own account.
• Play counts: Only instagram_reels exposes play_count — the standard feed API omits it.
• Session expiry: Cookies expire. Use instagram_server action=reload_cookies to refresh without restarting.
• Write operations: Like, comment, follow, upload, DM actions — rate limits apply. Avoid rapid consecutive writes.
• Anonymous hashtag blocks: Some hashtags (#swimwear, #fitness, etc.) block anonymous HTML scraping.
• Account restrictions: Comment, reply, and follow may return "something went wrong" on new or restricted accounts — this is Instagram-side, not a bug.

FAQ

Do I need to log in?
No. 30 tools work anonymously with no credentials. 48 tools require cookies.json. instagram_hashtag auto-switches based on whether cookies are present.

Why curl_cffi instead of requests?
Instagram blocks requests and aiohttp at the TLS handshake level by JA3/JA4 fingerprint. curl_cffi impersonates Chrome's TLS stack, bypassing this check.

How do I get play counts for reels?
Use instagram_reels. The standard feed API (instagram_feed_deep) does not include play_count.

What happens on rate limiting?
The adaptive rate limiter detects 429s, backs off (×0.7 RPS), rotates proxy, and retries. After 5 consecutive 429s the circuit breaker opens for 60s.

How do I use multiple Instagram accounts?
Set INSTAGRAM_MCP_COOKIES_<ALIAS> env vars (e.g., INSTAGRAM_MCP_COOKIES_BRAND=cookies_brand.json). Use instagram_sessions action=list to see available sessions.

Are exports/ files safe to commit?
No — they may contain PII. Add exports/ to .gitignore.

How do I refresh cookies without restarting?
instagram_server action=reload_cookies