instagram-personal-mcp

A Model Context Protocol server that wraps instagrapi so Claude (or any MCP client) can read, engage, and DM from a personal Instagram account — no Business/Creator switch, no Meta app review.

⚠️ Unofficial private API. This server uses Instagram's reverse-engineered mobile API (via instagrapi). It is not affiliated with or endorsed by Meta. Accounts driving private-API traffic can be rate-limited, challenged, or permanently disabled. Use a burner account until you trust your setup, keep activity natural, and don't connect over VPNs / datacenter IPs.

24 tools across auth, profile/read, engagement, and DMs.

Quick start

git clone https://github.com/AleemHaider/instagram-personal-mcp
cd instagram-personal-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Drop your creds in a .env:

cp .env.example .env
# edit: IG_USERNAME, IG_PASSWORD

Then run it:

instagram-personal-mcp

The first call (e.g. instagram_session_status or instagram_login) will authenticate and save a session file to ~/.config/instagram-personal-mcp/session.json. Subsequent runs reuse it.

Connect to Claude Desktop

Edit ~/.config/Claude/claude_desktop_config.json (Linux) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "instagram-personal": {
      "command": "instagram-personal-mcp",
      "env": {
        "IG_USERNAME": "your_username",
        "IG_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop.

Tools

Auth

Profile & read

Engagement

Direct messages

2FA flow

1. Call instagram_login (no code) — if 2FA is required you'll get {"error": true, "code": "2FA_REQUIRED", ...}.
2. Get the code from your authenticator / SMS.
3. Call instagram_login again with verification_code="123456".

Errors

Tools return structured errors instead of raising. Look for error: true and a machine-readable code:

• NOT_LOGGED_IN — call instagram_login first.
• LOGIN_REQUIRED — saved session was rejected; log in again.
• 2FA_REQUIRED — call instagram_login again with verification_code.
• CHALLENGE_REQUIRED — Instagram wants a security challenge solved; log in from the IG app / web once to clear it.
• RATE_LIMITED — PleaseWaitFewMinutes from upstream; back off.
• USER_NOT_FOUND / MEDIA_NOT_FOUND — bad input or removed content.

Development

pip install -e ".[dev]"
pytest

Why a separate project from instagram-mcp?

The sibling instagram-mcp wraps the official Instagram Graph API — Business/Creator accounts only, requires a Meta app and tokens, fully ToS-compliant. This project wraps the unofficial private API for personal accounts and carries the risks above. They're kept separate so the official one stays clean and reviewable.

License

MIT — see LICENSE.