Skip to main content
Glama
instagram-mcp

instagram-mcp

by Stupidoodle

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

Variable

Default

INSTAGRAM_USERNAME / INSTAGRAM_PASSWORD

Only needed to log in

INSTAGRAM_SESSION_FILE

.instagram_session

Saved session

INSTAGRAM_SUBSCRIBE

Chats to stream on start: alias=thread_id,...

INSTAGRAM_IDLE_MINUTES

5

Quiet minutes before an idle nudge (0 disables)

INSTAGRAM_IDLE_BACKOFF_AFTER_MINUTES

30

When nudges start backing off

INSTAGRAM_IDLE_MAX_MINUTES

240

Longest gap between nudges

INSTAGRAM_CONTROL_THREAD

A chat whose messages become operator commands

INSTAGRAM_DEBUG_PREFIX

debug:

Own messages with this prefix become operator commands

INSTAGRAM_TZ

host zone

Time zone for the idle event's clock

INSTAGRAM_MEDIA_DIR

media

Where download_attachment saves files

INSTAGRAM_SEEN_DB

seen.db

Live read receipts, so history knows when each message was seen (GET /seen)

INSTAGRAM_EPHEMERAL_DIR

$TMPDIR/instagram-ephemeral

Owner-only folder for view-once and replayable photos

INSTAGRAM_EPHEMERAL_TTL_MINUTES

15

View-once downloads are deleted this long after download

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

Variable

OTEL_EXPORTER_OTLP_ENDPOINT

Base URL, e.g. http://127.0.0.1:4318

OTEL_TRACES_EXPORTER / OTEL_METRICS_EXPORTER / OTEL_LOGS_EXPORTER

none leaves that signal out

OTEL_METRIC_EXPORT_INTERVAL

Milliseconds between metric pushes (SDK default 60000, nexi 15000)

OTEL_RESOURCE_ATTRIBUTES

Extra resource attributes, e.g. deployment.environment.name=prod

OTEL_SERVICE_NAME

Overrides instagram-bridge / instagram-mcp

DM_PERSONA_DIR

Thin client: the persona folder (default: PWD)

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

Available Tools

27 tools
download_attachmentA

Download a message's photo, video or voice clip; returns the path on the bridge host.

View-once media lands in a temporary folder and is deleted soon; never keep it.

Args: message_id: Message id from the channel event. to: Chat alias. Omit for the sole subscribed target.

Inputs: message_id (required), to. Returns: object

get_chat_logA

Get conversation as a readable chat log. Optimized for LLM analysis.

Plain-text chronological log, ~5x smaller than JSON. Use get_messages for structured fields.

Args: thread_id: ID of the thread to get messages from. amount: Maximum number of messages to fetch (default: 50). offset: Skip the N most recent messages (default: 0).

Returns: Object with 'thread_id', 'log' (plain text), 'count', 'offset', 'has_more'.

Inputs: thread_id (required), amount, offset. Returns: object

get_message_idsA

List this account's recent messages with their ids, newest first (for unsend).

That is yours and the ones the owner sent from their phone.

Args: to: Chat alias. Omit for the sole subscribed target. filter: Only messages whose text contains this substring. limit: How many to return (default 10).

Inputs: to, limit, filter. Returns: object

get_messagesB

Get messages from a thread.

Args: thread_id: ID of the thread to get messages from. amount: Maximum number of messages to fetch (default: 20). offset: Skip the N most recent messages (default: 0).

Returns: Object with 'thread_id', 'messages' (sender, text, media_type, timestamp, seen_since when viewer's, share for a shared reel/post/story), 'count', 'offset', 'has_more'.

Inputs: thread_id (required), amount, offset. Returns: object

get_pending_threadsB

Get pending message request threads.

Returns: Object with 'threads' array of pending threads and 'count'.

Inputs: no named parameters. Returns: object

get_threadB

Get a specific thread with its messages.

Args: thread_id: ID of the thread to fetch. amount: Maximum number of messages to fetch (default: 20).

Returns: Thread object with thread_id, thread_title, users, is_group, and a messages array (message_id, sender, text, media_type, timestamp, ...).

Inputs: thread_id (required), amount. Returns: object

hide_threadC
Destructive

Hide/delete a thread from inbox.

Args: thread_id: ID of the thread to hide.

Inputs: thread_id (required). Returns: object

list_subscriptionsA

List subscribed chats and their aliases.

Inputs: no named parameters. Returns: object

list_threadsB

Get direct message threads from inbox.

Args: amount: Maximum number of threads to fetch (default: 20).

Returns: Object with 'threads' array (thread_id, thread_title, users, is_group, is_muted, unread, last_activity_at) and 'count'.

Inputs: amount. Returns: object

mark_readA

Optional read receipt ("Seen") up to the newest of these messages.

Args: message_ids: Message ids from channel events; the newest one is used. to: Chat alias. Omit for the sole subscribed target.

Inputs: message_ids (required), to. Returns: object

mark_thread_unreadB

Mark a thread as unread.

Args: thread_id: ID of the thread to mark unread.

Inputs: thread_id (required). Returns: object

mute_threadC

Mute notifications for a thread.

Args: thread_id: ID of the thread to mute.

Inputs: thread_id (required). Returns: object

open_shareA

Open a shared reel, post or story: download it and see what's in it.

Returns the caption, the photos, and per video its file, length in seconds and a preview: 6 evenly spaced frames stitched into one image, left to right, top to bottom. Read the preview first. For a closer look, pull frames yourself: ffmpeg -loglevel error -ss <second> -i <file> -frames:v 1 /tmp/f.jpg (one frame) or -vf fps=2 /tmp/f-%02d.jpg (every half second), then Read them. For what is said, call transcribe_share.

Args: message_id: Message id of the share, from the channel event. to: Chat alias. Omit for the sole subscribed target.

Inputs: message_id (required), to. Returns: object

reactA

React to a message with an emoji. An empty emoji removes your reaction.

Args: message_id: Message id (from a channel event or get_message_ids). emoji: E.g. "❀️"; "" removes your reaction. to: Chat alias. Omit for the sole subscribed target.

Inputs: emoji (required), message_id (required), to. Returns: object

replyA

Send a text message. Address by alias via to, or omit it for the sole target.

Args: text: Message text. to: Chat alias (e.g. "alex"). Omit for the sole subscribed target.

Inputs: text (required), to. Returns: object

search_threadsC

Search threads by username or title.

Args: query: Search query (username or thread title).

Returns: Object with 'query', 'threads' array of matches, and 'count'.

Inputs: query (required). Returns: object

send_audioB

Send an audio file as a voice message (bridge converts to .m4a if needed).

The path is read on the bridge host.

Args: file_path: Path to the audio file (on the bridge host). to: Chat alias. Omit for the sole subscribed target.

Inputs: file_path (required), to. Returns: object

send_fileA

Send a photo or video (Instagram DMs take no other file types).

The path is read on the bridge host (where Instagram is connected).

Args: file_path: Path to the photo or video (on the bridge host). to: Chat alias. Omit for the sole subscribed target. view_mode: "once" (view once) or "replayable" (allow replay) sends it as a disappearing photo/video (videos: H.264 mp4). Omit for a normal one.

Inputs: file_path (required), to, view_mode. Returns: object

send_typingA

Optional typing indicator: they see "typing..." while composing is true.

Args: to: Chat alias. Omit for the sole subscribed target. composing: True starts the indicator, false stops it.

Inputs: to, composing. Returns: object

set_idleA

Tune how long a chat must be quiet before you get an [idle] nudge.

Ramp it up to back off (60 = hourly while they're gone) or 0 to pause. Resets to the default the moment they next message.

Args: minutes: Quiet-time threshold in minutes (0 pauses nudges). to: Chat alias. Omit for the sole subscribed target.

Inputs: minutes (required), to. Returns: object

share_mediaC

Share an Instagram post into a thread.

Args: media_id: ID of the Instagram media/post to share. thread_id: Thread to share it into.

Inputs: media_id (required), thread_id (required). Returns: object

share_profileB

Share a user's Instagram profile into a thread.

Args: user_id: ID of the user profile to share. thread_id: Thread to share it into.

Inputs: user_id (required), thread_id (required). Returns: object

subscribeA

Subscribe to an Instagram thread and give it a short alias.

This is the ONE place a raw thread id is entered (from list_threads or search_threads). Only subscribed chats deliver events.

Args: chat_id: Thread id, e.g. '340282366841700000000000000000000000001'. alias: Short memorable handle (e.g. 'alex'). Derived from the thread title if omitted.

Inputs: chat_id (required), alias. Returns: object

transcribe_shareA

Transcribe what is said in a shared reel's (or post's) videos.

Only when the words matter: music-only reels give noise. Reuses the open_share download.

Args: message_id: Message id of the share, from the channel event. to: Chat alias. Omit for the sole subscribed target.

Inputs: message_id (required), to. Returns: object

unmute_threadB

Unmute notifications for a thread.

Args: thread_id: ID of the thread to unmute.

Inputs: thread_id (required). Returns: object

unsendA
Destructive

Unsend a message this account sent, for everyone. Get the id from get_message_ids.

That covers yours and the ones the owner sent from their phone: when the operator tells you to delete one, do it.

Args: message_id: Id of the message. to: Chat alias. Omit for the sole subscribed target.

Inputs: message_id (required), to. Returns: object

unsubscribeB

Unsubscribe from a chat. Stops delivering its events.

Args: to: Alias or thread id to unsubscribe.

Inputs: to (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools target distinct resources+actions (send, react, unsend, mute, subscribe), and descriptions clarify intent well. However, get_thread, get_messages, and get_chat_log all retrieve the same thread content with only format/purpose differences, creating some overlap an agent could misselect between.

    Naming Consistency4/5

    Names are consistently snake_case verb_noun (list_threads, get_messages, share_media, mark_thread_unread), which is highly readable. Minor deviation: a few bare-verb tools (subscribe, reply, react, unsend) lack the noun component, but they remain clear and consistent within themselves.

    Tool Count3/5

    27 tools is heavy and slightly over the comfortable range for this domain. Several could be consolidated (the three message-retrieval tools, separate mute/unmute), but the DM bridge legitimately needs subscription, messaging, thread-management, and sharing surfaces.

    Completeness4/5

    The surface covers a full DM lifecycle: subscribe/unsubscribe to events, send/reply/audio/file, react, unsend, mark read, typing, attachment download, thread management (hide, mute, mark unread), search, and sharing reels/profiles. Minor gaps like group creation or blocking exist but core workflows are well covered.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables sending and receiving Instagram Direct Messages, managing conversations, downloading media, viewing user profiles and stories, and interacting with posts through natural language in Claude.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, send, and manage Instagram direct messages, including viewing conversations, sending DMs to users, reacting to messages, and searching for users by username.
      10
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Claude to Instagram through Meta's official API, enabling users to retrieve account insights, analyze professional profiles, publish photos/carousels/reels/stories, manage comments, read and respond to Direct messages, and call any Graph API endpoint.
      39 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables sending, reading, and managing Instagram Direct Messages from your own account through Claude Desktop or Cursor, including sending text, photo, and video messages, listing and searching chats and threads, downloading media from messages, and looking up user profiles, followers, posts, and stories. It also supports marking messages as seen and checking pending inbox threads.
      -