instagram-mcp
Allows reading and sending Instagram direct messages, managing threads (list, get, search, hide, mute, unmute), sending media, and autonomous conversation handling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@instagram-mcp check my pending message requests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 aliasreply- Send a text messagesend_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 messagesdownload_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 itset_idle- Tune the idle-nudge cadence per chat
Reading
list_threads/get_thread/search_threads/get_pending_threads- Browse conversationsget_messages/get_chat_log- History, with read receipts (seen_since)
Inbox and sharing
hide_thread/mark_thread_unread/mute_thread/unmute_threadshare_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
Install:
uv syncLog 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-loginAdd 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" } } } }Start Claude Code with the channel enabled:
claude --dangerously-load-development-channels server:instagram
Configuration
Variable | Default | |
| Only needed to log in | |
|
| Saved session |
| Chats to stream on start: | |
|
| Quiet minutes before an idle nudge (0 disables) |
|
| When nudges start backing off |
|
| Longest gap between nudges |
| A chat whose messages become operator commands | |
|
| Own messages with this prefix become operator commands |
| host zone | Time zone for the idle event's clock |
|
| Where |
|
| Live read receipts, so history knows when each message was seen ( |
|
| Owner-only folder for view-once and replayable photos |
|
| 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 | |
| Base URL, e.g. |
|
|
| Milliseconds between metric pushes (SDK default 60000, nexi 15000) |
| Extra resource attributes, e.g. |
| Overrides |
| Thin client: the persona folder (default: |
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 andhttp.server.request.duration; oneinstagram.event <type>span per MQTT event with the media download and the call to the transcriber inside it; aninstagram.sendspan per send. Each SSE event carries its span'straceparent. 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'stools/call <tool>spans tagged with the persona, and adm.channel.deliverspan 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.jsonenvand 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-loginThen run uv run pytest -m e2e.
Tech Stack
Python 3.14 + uv
MCP Python SDK 2 (
MCPServer), pushing events as a Claude Code channelinstagrapi 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_sinceAutonomous 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 toolsdownload_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_threadCDestructive
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
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
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
unmute_threadB
Unmute notifications for a thread.
Args: thread_id: ID of the thread to unmute.
Inputs: thread_id (required). Returns: object
unsendADestructive
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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Schedule Instagram reels, posts and stories, run comment-to-DM automations, and read analytics.
Read and search your Instagram, WhatsApp and LinkedIn DMs and prepare follow-ups you approve.
Lets Claude and AI agents post and schedule on Instagram, TikTok, LinkedIn and 5 more networks.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceConnects 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 npmMIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-