Instagram DM MCP

What is Instagram DM MCP about?

Instagram DM MCP provides a Model Context Protocol server that lets you automate sending and managing Instagram Direct Messages from your own account. It integrates with AI tools, allowing conversational agents to perform messaging actions without manual intervention.

How to use Instagram DM MCP?

1. Install Python 3.11+ and the required dependencies (uv sync or pip install -r requirements.txt).
2. Configure credentials – run python setup_env.py to create a secure .env file with INSTAGRAM_USERNAME and INSTAGRAM_PASSWORD, or supply them via command‑line arguments.
3. Start the MCP server – execute python src/mcp_server.py (or use the provided configuration snippets for Claude Desktop or Cursor).
4. Connect the server in Claude Desktop (claude_desktop_config.json) or Cursor (mcp.json) using the example JSON configurations.
5. Invoke tools such as send_message, list_chats, download_media_from_message, etc., from your AI assistant.

Key features of Instagram DM MCP

• Send text, photo, or video direct messages.
• Retrieve chat threads, messages, and media.
• Download direct‑uploaded media or shared posts/reels from DMs.
• Mark messages as seen, search threads, and fetch user info.
• Access follower/following lists, recent posts, stories, and like media.
• Automatic session management to avoid login hangs.

Use cases of Instagram DM MCP

• Customer support: Automate replies to common inquiries via Instagram DMs.
• Marketing campaigns: Bulk‑send promotional messages or media to targeted users.
• Content curation: Pull user stories, posts, or media for analysis or reposting.
• Social listening: Search and monitor DM conversations for brand mentions.
• AI assistant integration: Enable Claude or other agents to act on Instagram messaging within workflows.

FAQ from the Instagram DM MCP

Q: Which Python version is required? A: Python 3.11 or newer.

Q: Do I need the Claude Desktop app? A: It’s one supported client; you can also use Cursor or any MCP‑compatible tool.

Q: How are credentials stored securely? A: Use the interactive setup_env.py script to create a .env file that is ignored by Git.

Q: What if login hangs? A: The server creates and reuses session files (e.g., username_session.json) to maintain authentication state.

Q: Can I run the server inside a container? A: Yes, as long as the container has Python 3.11+, the required packages, and the environment variables set.

Instagram DM MCP server

This is a Model Context Protocol (MCP) server for sending instagram Direct Messages.

With this you can send Instagram Direct Messages from your account (more capabilities coming soon).

Here's an example of what you can do when it's connected to Claude.

https://github.com/user-attachments/assets/9c945f25-4484-4223-8d6b-5bf31243464c

To get updates on this and other projects we work on enter your email here

---

Installation

Prerequisites

• Python 3.11+
• Anthropic Claude Desktop app (or Cursor)
• Pip (Python package manager), install with python -m pip install
• An instagram account

Steps

1. Clone this repository

   git clone https://github.com/trypeggy/instagram_dm_mcp.git
   cd instagram_dm_mcp
   

2. Install dependencies

• Using uv (recommended):

  uv sync
  

• Using Pip:

  pip install -r requirements.txt
  

3. Configure Instagram credentials

   You have two options for providing your Instagram credentials:

   Option A: Environment Variables (Recommended)

   Quick Setup (Recommended):

   Run the helper script:

   python setup_env.py
   

   This will interactively prompt you for your credentials and create the .env file securely.

   Manual Setup:

   Create a .env file in the project root:

   cp env.example .env
   

   Then edit .env with your actual credentials:

   INSTAGRAM_USERNAME=your_instagram_username
   INSTAGRAM_PASSWORD=your_instagram_password
   

   Option B: Command Line Arguments

   You can still pass credentials as command line arguments (less secure).

4. Connect to the MCP server

   For Claude Desktop:

   Save this as claude_desktop_config.json in your Claude Desktop configuration directory at:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   For Cursor:

   Save this as mcp.json in your Cursor configuration directory at:

   ~/.cursor/mcp.json
   

   Configuration with Environment Variables (Recommended):

   • Using uv

   {
     "mcpServers": {
       "instagram_dms": {
           "command": "uv",
           "args": [
             "run",
             "--directory",
             "PATH/TO/instagram_dm_mcp",
             "python",
             "src/mcp_server.py"
           ]
        }
      }
    }
   

   • Using Python

   {
     "mcpServers": {
       "instagram_dms": {
         "command": "python",
         "args": [
           "{{PATH_TO_SRC}}/instagram_dm_mcp/src/ mcp_server.py"
         ]
       }
     }
   }
   

   Configuration with Command Line Arguments:

   {
     "mcpServers": {
       "instagram_dms": {
         "command": "python",
         "args": [
           "{{PATH_TO_SRC}}/instagram_dm_mcp/src/mcp_server.py",
           "--username",
           "{{YOUR_INSTAGRAM_USERNAME}}",
          "--password",
          "{{YOUR_INSTAGRAM_PASSWORD}}"
         ]
       }
     }
   }
   

5. Restart Claude Desktop / Cursor

   Open Claude Desktop and you should now see the Instagram DM MCP as an available integration.

   Or restart Cursor.

---

Usage

Below is a list of all available tools and what they do:

Tool Name	Description
send_message	Send an Instagram direct message to a user by username.
send_photo_message	Send a photo as an Instagram direct message to a user by username.
send_video_message	Send a video as an Instagram direct message to a user by username.
list_chats	Get Instagram Direct Message threads (chats) from your account, with optional filters/limits.
list_messages	Get messages from a specific Instagram Direct Message thread by thread ID. Now exposes item_type and shared post/reel info for each message. Use this to determine which download tool to use.
download_media_from_message	Download a direct-uploaded photo or video from a DM message (not for shared posts/reels/clips).
download_shared_post_from_message	Download media from a shared post, reel, or clip in a DM message (not for direct uploads).
list_media_messages	List all messages containing direct-uploaded media (photo/video) in a DM thread.
mark_message_seen	Mark a specific message in an Instagram Direct Message thread as seen.
list_pending_chats	Get Instagram Direct Message threads from your pending inbox.
search_threads	Search Instagram Direct Message threads by username or keyword.
get_thread_by_participants	Get an Instagram Direct Message thread by participant user IDs.
get_thread_details	Get details and messages for a specific Instagram Direct Message thread by thread ID.
get_user_id_from_username	Get the Instagram user ID for a given username.
get_username_from_user_id	Get the Instagram username for a given user ID.
get_user_info	Get information about a specific Instagram user by username.
search_users	Search for Instagram users by username
get_user_stories	Get recent stories from a specific Instagram user by username.
like_media	Like or unlike a specific media post by media ID.
get_user_followers	Get a list of followers for a specific Instagram user by username.
get_user_following	Get a list of users that a specific Instagram user is following by username.
get_user_posts	Get recent posts from a specific Instagram user by username.

---

Troubleshooting

Instagram Login Hanging: The server now includes automatic session management to prevent login hangs. Session files (e.g., username_session.json) are automatically created and reused to maintain authentication state between runs.

For additional Claude Desktop integration troubleshooting, see the MCP documentation. The documentation includes helpful tips for checking logs and resolving common issues.

---

Feedback

Your feedback will be massively appreciated. Please tell us which features on that list you like to see next or request entirely new ones.

---

License

This project is licensed under the MIT License.