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

uv sync

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

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

{
      "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:

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.