Instagram MCP Server

An MCP server that lets Claude read and send Instagram DMs. Built entirely by Claude in a 3-hour vibe coding session with auto-accept enabled.

Features

New DMs, typing, reactions, read receipts, edits and unsends arrive over Instagram's MQTT connection and are pushed straight into the Claude Code session as channel events. Nothing polls. The channel tools use the same names as the WhatsApp channel.

Channel (realtime)

• subscribe / unsubscribe / list_subscriptions - Pick which chats stream events, each under a short alias

• reply - Send a text message

• send_file / send_audio - Send a photo or video (optionally view once or allow replay) / a voice message (converted to .m4a)

• send_typing / mark_read - Typing indicator / "Seen"

• react / unsend / get_message_ids - React, take back your own messages

• download_attachment - Fetch a photo, video or voice clip (view-once media only to a temporary folder)

• open_share / transcribe_share - Open a shared reel, post or story (files, a frame preview per video) / hear what is said in it

• set_idle - Tune the idle-nudge cadence per chat

Reading

• list_threads / get_thread / search_threads / get_pending_threads - Browse conversations

• get_messages / get_chat_log - History, with read receipts (seen_since)

Inbox and sharing

• hide_thread / mark_thread_unread / mute_thread / unmute_thread

• share_media / share_profile

Shared reels, posts and stories

A share arrives as [reel by @author: caption — link] with its cover image in media_path, whoever sent it. The caption costs one API call per share. The video is only downloaded when a persona calls open_share, which returns 6 frames stitched into one preview; the tool description shows how to pull more frames with ffmpeg. transcribe_share is separate, so nothing is transcribed by accident.

Idle nudges

A quiet subscribed chat gets an idle event every INSTAGRAM_IDLE_MINUTES (5). Once it has been quiet for INSTAGRAM_IDLE_BACKOFF_AFTER_MINUTES (30), each nudge doubles the gap to the next, up to INSTAGRAM_IDLE_MAX_MINUTES (240). Any activity resets it.

Related MCP server: Instagram DMs MCP

The /dm Skill - Autonomous Conversations

The real magic. Launch Claude as an autonomous agent that handles entire DM conversations:

/dm @username "your goal here"

Claude will:

• Read conversation history for context

• Send messages with natural timing and double-texting

• Wait for replies (adjusting patience based on their energy)

• Handle interjections mid-thought

• Know when to push forward vs back off

• Run for hours/days until the goal is achieved or abandoned

War Stories (Anonymized)

The AGI Moment

Two Claude instances accidentally ran the same conversation simultaneously. When Instance B noticed messages it didn't send appearing in the thread ("wait that's not what I said"), instead of panicking or erroring out, it just... adapted. Read the new context, figured out someone else was also texting, and smoothly continued the conversation incorporating both threads of dialogue.

The Persistence Play

Target said "give up" (direct quote). Claude's response? Playful persistence. Three messages later, same person responds with "what a fighter 😊". Went from rejection to engaged in under 5 minutes through pure conversational momentum.

The Overnight Wait

After a late-night conversation, Claude set a 2-hour wait for morning instead of triple-texting at midnight. When the timeout hit, it logged "She probably actually went to sleep this time" and queued a fresh opener for morning. Patience as a strategy.

The Read Receipt Pain

seen_since: 47 - They saw your message 47 minutes ago. The feature works. The emotional damage is real.

The Rogue Sessions

Discovered that background agents survive terminal closure (daemonized processes with no controlling TTY). Had to hunt down and kill Claude instances that were still running conversations hours after the terminal was closed. One was found via ps aux | grep python still polling Instagram at 2am.

Natural Double-Texting

Using send_and_check, Claude sends a message, syncs, and checks if they interjected. This enables natural rapid-fire texting:

"bro what is that 💀"     -> no interjection, continue thought
"where did you get that"  -> interjection detected! they said "wait"

Now Claude can decide: engage with their "wait" or finish the thought.

Setup

1. Install:

   uv sync

2. Log in once, in a normal terminal (the 2FA prompt needs a keyboard). It asks for the username, the password (hidden) and the 2FA code, and saves .instagram_session:

   read "?Username: " U && read -s "?Password: " P && echo && INSTAGRAM_USERNAME="$U" INSTAGRAM_PASSWORD="$P" uv run instagram-mcp-login

3. Add the server to your project's .mcp.json:

   {
     "mcpServers": {
       "instagram": {
         "command": "uv",
         "args": ["run", "--directory", "/path/to/instagram-mcp", "instagram-mcp"],
         "env": { "INSTAGRAM_SUBSCRIBE": "alex=340282366841700000000000000000000000001" }
       }
     }
   }

4. Start Claude Code with the channel enabled:

   claude --dangerously-load-development-channels server:instagram

Configuration

Telemetry

Off unless OTEL_EXPORTER_OTLP_ENDPOINT is set (and OTEL_SDK_DISABLED is not true). With it, the bridge and every thin client send traces, metrics and logs over OTLP/HTTP to that endpoint, under the DM platform's telemetry contract (service namespace dm).

The SDK reads these from the process environment (the systemd unit, the env of .mcp.json), not from .env.

• Bridge (instagram-bridge, instance: the hostname): dm.bridge.* metrics and http.server.request.duration; one instagram.event <type> span per MQTT event with the media download and the call to the transcriber inside it; an instagram.send span per send. Each SSE event carries its span's traceparent. On nexi the unit turns OTLP logs off: the JSON lines on stdout go to the journal.

• Thin client (instagram-mcp, instance: the persona folder, dm.persona): dm.channel.* metrics, mcp.server.operation.duration, the MCP SDK's tools/call <tool> spans tagged with the persona, and a dm.channel.deliver span per event that continues the bridge's trace. It logs JSON to stderr and, when on, over OTLP. Add the variables to the persona's .mcp.json env and relaunch the session.

Every signal, name and label, the reply latency and the probe routes (/health, /ready) are in docs/observability.md.

Logs are one JSON object per line: time, level, msg, service, trace_id and span_id inside a span, then fields such as message_id, kind or error_type. Message text, names, usernames, user ids and thread ids never go into telemetry or INFO+ logs; an exception logs its class and frames, not its message.

E2E tests

The e2e tests message between your account and a second test account. Log the test account in the same way, saving to .instagram_session_bot2:

read "?Bot username: " U && read -s "?Bot password: " P && echo && INSTAGRAM_USERNAME="$U" INSTAGRAM_PASSWORD="$P" INSTAGRAM_SESSION_FILE=.instagram_session_bot2 uv run instagram-mcp-login

Then run uv run pytest -m e2e.

Tech Stack

• Python 3.14 + uv

• MCP Python SDK 2 (MCPServer), pushing events as a Claude Code channel

• instagrapi for the Instagram API, raw MQTToT for realtime

• 361 unit and integration tests, plus a stdio wire test for the channel

Disclaimer

Don't be weird with this. Don't spam people. Don't let Claude say unhinged things to your crush.

Neither the human nor Claude are responsible for:

• Account bans

• Quantified rejection via seen_since

• Autonomous agents running conversations while you sleep

• Whatever Claude decides to say when given free rein

Built by Claude | Human mass-approved tool calls | @Stupidoodle