Instagram DM MCP
Send, read and search Instagram DMs from your AI client: 22 tools for messages, media, threads and user lookups.
Add to your client
Copy the config for your MCP client and paste it into its config file.
git clone https://github.com/trypeggy/instagram_dm_mcp.git && cd instagram_dm_mcp && uv syncPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"instagram-dm-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"PATH/TO/instagram_dm_mcp",
"python",
"src/mcp_server.py"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.11+
- An Instagram account (logs in with username/password)
- uv (recommended) or pip to install dependencies
- Claude Desktop or Cursor as the MCP client
About Instagram DM MCP
The server runs locally as a stdio process: your MCP client (Claude Desktop or Cursor) launches it via uv run from your cloned repo, it logs into Instagram with the credentials in your .env, and it keeps a session file per username so subsequent runs skip the login (the README notes this session management was added specifically to prevent login hangs).
The tool surface maps to real DM workflows rather than a thin send-only wrapper. You can triage the pending inbox (list_pending_chats), search threads by keyword or username, mark messages seen, and resolve user IDs in both directions. list_messages exposes each message's item_type and shared post/reel info so the agent knows whether to call download_media_from_message (direct uploads) or download_shared_post_from_message (shared posts, reels, clips).
The trade-offs are inherent to the approach: there is no official Instagram DM API for personal accounts, so this works by logging in as you with a password — which Instagram's automation detection can flag. There is also no PyPI package; you run from a cloned checkout, and the client config must point at that directory (uv run --directory PATH/TO/instagram_dm_mcp).
It is MIT-licensed and needs Python 3.11+. Credentials can alternatively be passed as --username / --password CLI args in the config, but the README itself calls that less secure than the .env route.
Tools & capabilities (22)
send_messageSend an Instagram DM to a user by username.
send_photo_messageSend a photo as a DM to a user by username.
send_video_messageSend a video as a DM to a user by username.
list_chatsGet DM threads from your account, with optional filters and limits.
list_messagesGet messages in a thread by thread ID, including item_type and shared post/reel info.
download_media_from_messageDownload a direct-uploaded photo or video from a DM message.
download_shared_post_from_messageDownload media from a shared post, reel, or clip in a DM message.
list_media_messagesList all messages containing direct-uploaded media in a thread.
mark_message_seenMark a specific message in a thread as seen.
list_pending_chatsGet DM threads from your pending inbox.
search_threadsSearch DM threads by username or keyword.
get_thread_by_participantsGet a DM thread by participant user IDs.
get_thread_detailsGet details and messages for a thread by thread ID.
get_user_id_from_usernameResolve an Instagram user ID from a username.
get_username_from_user_idResolve a username from an Instagram user ID.
get_user_infoGet profile information for a user by username.
search_usersSearch Instagram users by username.
get_user_storiesGet recent stories from a user by username.
like_mediaLike or unlike a media post by media ID.
get_user_followersList followers of a user by username.
get_user_followingList accounts a user follows, by username.
get_user_postsGet recent posts from a user by username.
What this server can do
Instagram DM MCP provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Triage your DM inbox: list pending chats, summarize threads, mark messages seen
- Send text, photo or video DMs to a username straight from Claude
- Download media or shared reels/posts from a conversation for archiving
- Look up a user's followers, stories and recent posts before replying
Quick setup
- 1git clone https://github.com/trypeggy/instagram_dm_mcp.git && cd instagram_dm_mcp
- 2Install dependencies: uv sync (or pip install -r requirements.txt)
- 3Run python setup_env.py to create the .env with INSTAGRAM_USERNAME and INSTAGRAM_PASSWORD
- 4Add the uv run --directory PATH/TO/instagram_dm_mcp config block to claude_desktop_config.json or ~/.cursor/mcp.json
- 5Restart Claude Desktop / Cursor and check that instagram_dms shows up as an integration
Security notes
You hand the server your real Instagram username and password (stored in a local .env plus reused session files), and it can read and send DMs as you. This is unofficial account automation, not the Meta API — Instagram may restrict accounts that automate logins, so consider a secondary account.
Instagram DM MCP FAQ
Is the Instagram DM MCP safe for my main account?
Treat it as risky for a main account: it is unofficial automation that logs in with your real username and password and acts as you, and Instagram can flag automated behavior. Credentials stay local (in your .env and session files), but many users run it on a secondary account first. Session reuse at least avoids repeated logins.
Do I need a Meta developer account or Instagram API access?
No. It authenticates with a normal Instagram username and password — no developer app, access tokens, or business account required. That is also exactly why it is not an official integration.
Can it read and download messages, or only send them?
Both. list_chats, list_messages and search_threads read conversations; download_media_from_message and download_shared_post_from_message pull photos, videos and shared reels; list_pending_chats covers the request inbox. Sending supports text, photos and videos.
Alternatives to Instagram DM MCP
Compare all alternatives →
Connect your personal WhatsApp: search, read and send messages and media locally
Lets agents read LinkedIn profiles, companies, jobs and messages through your own logged-in browser session.
Powerful Slack MCP with stdio/SSE/HTTP, DMs, group DMs and no-admin token auth
Compare Instagram DM MCP with: