Instagram DM

instagram_dm_mcp: Instagram Direct Messages MCP Server

What is instagram_dm_mcp?

instagram_dm_mcp is a Model Context Protocol (MCP) server that enables sending Instagram Direct Messages from your account. It allows integration with large language models (LLMs) like Claude and Cursor to automate Instagram messaging and other interactions.

How to use instagram_dm_mcp?

Prerequisites:

Python 3.11+
Anthropic Claude Desktop app (or Cursor)
Pip (Python package manager)
An Instagram account

Installation Steps:

Clone the repository:

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

Install dependencies:
- Using uv (recommended):
```
uv sync
```
- Using pip:
```
pip install -r requirements.txt
```
Configure Instagram credentials:
- Option A (Recommended - Environment Variables): Run python setup_env.py to interactively set up credentials, or manually create a .env file with INSTAGRAM_USERNAME and INSTAGRAM_PASSWORD.
- Option B (Command Line Arguments): Pass credentials directly as command-line arguments (less secure).
Connect to the MCP server: Configure Claude Desktop or Cursor by saving a JSON configuration file (claude_desktop_config.json for Claude or mcp.json for Cursor) with the appropriate command to run the mcp_server.py script. Examples for both environment variables and command-line arguments are provided in the README.
Restart Claude Desktop / Cursor: The Instagram DM MCP should now be available as an integration.

Key Features of instagram_dm_mcp

The project provides a comprehensive set of tools for Instagram Direct Messages and other interactions:

Messaging: send_message, send_photo_message, send_video_message.
Chat Management: list_chats, list_messages, mark_message_seen, list_pending_chats, search_threads, get_thread_by_participants, get_thread_details.
Media Handling: download_media_from_message, download_shared_post_from_message, list_media_messages.
User Information: get_user_id_from_username, get_username_from_user_id, get_user_info, search_users, get_user_stories, get_user_followers, get_user_following, get_user_posts.
Engagement: like_media.

Use Cases of instagram_dm_mcp

Automated Instagram Marketing: Send personalized direct messages to followers or potential customers based on LLM-driven campaigns.
Customer Support: Automate responses to common queries received via Instagram DMs.
Content Distribution: Automatically send new posts or media to specific users or groups.
Community Management: Manage and interact with your Instagram community more efficiently.
Data Collection: Programmatically retrieve chat histories, user information, and media for analysis.

FAQ from the Project

Q: My Instagram login is hanging. What should I do? A: The server 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 troubleshooting with Claude Desktop integration, refer to the MCP documentation for tips on checking logs and resolving common issues.

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

PS: Join our Twitter community for all things MCP

Hackathon Submission

Build anything using this Instagram DM MCP (can be technical, no-code or low-code) and submit!

No restrictions, open to anyone/anywhere to join.

Note: submisions due by Friday 27 June 11:59PM PST

Three cash prizes up for grabs

$5k USD - Breaking the internet (go viral AF)
$2.5k USD - Technical Sorcery (coolest technical implementation)
$2.5k USD - Holy Sh*t Award (make our jaws drop)

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

Clone this repository

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

Install dependencies

Using uv (recommended):
```
uv sync
```
Using Pip:
```
pip install -r requirements.txt
```

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

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

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.

Instagram DM Overview