Instagram DM MCP Server

How to use

You connect the Instagram DM MCP server to your MCP client (such as Claude Desktop or Cursor) to perform common Instagram Direct Message actions. You can send messages and media, list chats and messages, download media from DMs, and manage conversations directly from your MCP workflow. Start by configuring credentials so the server can access your Instagram account, then run the MCP server locally or expose it through your MCP client as an integration. Once connected, use the available tool endpoints to interact with your DMs in real time.

How to install

Prerequisites: Install Python 3.11 or newer, ensure Pip is available, and have an Instagram account. You can also run the MCP server through uv (uv is recommended) or via a direct Python command.

# 1. Clone the project
git clone https://github.com/trypeggy/instagram_dm_mcp.git
cd instagram_dm_mcp

# 2. Install dependencies
# Using uv (recommended)
uv sync

# Or using Pip
pip install -r requirements.txt

Configure your Instagram credentials. You may provide credentials via environment variables or as command line arguments. A quick interactive setup can create a secure .env file for you, or you can manually create and edit the .env file in the project root.

Option A: Environment Variables (Recommended) — Quick Setup:

python setup_env.py

Option A cont'd — Manual Setup (if you prefer): create a .env file and fill in your credentials.

cp env.example .env
```
```
INSTAGRAM_USERNAME=your_instagram_username
INSTAGRAM_PASSWORD=your_instagram_password

Option B: Command Line Arguments (less secure): supply credentials directly when starting the server.

Connect to the MCP server from Claude Desktop or Cursor. Use the provided configuration snippets to integrate the MCP server into your client.

For Claude Desktop: Save the following configuration as claude_desktop_config.json in your Claude Desktop configuration directory.

For Cursor: Save the following configuration as mcp.json in your Cursor configuration directory.

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"
      ]
    }
  }
}

Configuration with Python

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

Configuration with Command Line Arguments (start the server with your credentials):

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

Restart Claude Desktop or Cursor after adding the configuration. You should then see the Instagram DM MCP as an available integration.

Additional configuration and notes

Environment management and session handling improve reliability. Session files (for example, username_session.json) are created and reused to maintain authentication state between runs.

If you need more troubleshooting assistance with the MCP integration, check the MCP-related guidance for your client and verify that the server is running and reachable from your client.

Troubleshooting

If you encounter issues with Instagram login hanging, ensure your session management is functioning and that credentials are correct. Restart the MCP server and client after updating credentials or environment settings.

Feedback

Share your experience and request new features. Your input helps shape future improvements to the Instagram DM MCP server.

License

This project is licensed under the MIT License.

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. Exposes item_type and shared post/reel info for each message.

download_media_from_message

Download a direct-uploaded photo or video from a DM message.

download_shared_post_from_message

Download media from a shared post, reel, or clip in a DM message.

list_media_messages

List all messages containing direct-uploaded media 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 a DM thread by participant user IDs.

get_thread_details

Get details and messages for a specific DM 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.