instagram_dm_mcp

This MCP server enables programmatic control of your Instagram Direct Messages from within Claude (or other MCP-enabled clients). It exposes a suite of tools that let you send DMs, fetch threads and messages, download media from messages, manage read/status, and search or list conversations with your connected Instagram account. Tools like send_message, list_chats, list_messages, download_media_from_message, and get_user_info are designed to be called from within the MCP context to automate Instagram DM workflows or build chat-based automation.

To use it, connect the instagram_dms MCP server to your MCP client (Claude Desktop or Cursor) by configuring the mcpServers section as shown in the installation guidance. Provide your Instagram credentials (environment variables recommended) so the server can authenticate and access your DMs. Once configured and restarted, you’ll see instagram_dms as an available integration and can start issuing commands to perform actions such as sending messages, listing threads, or downloading media directly from DMs.

Prerequisites:

• Python 3.11+
• An Instagram account
• Pip (Python package manager)
• MCP client (Claude Desktop or Cursor) for integration

Steps:

1. Clone the repository:

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

2. Create and activate a Python environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure credentials:

• Option A (recommended): Environment variables via .env or directly in mcp_config
• Option B: Provide credentials via command line arguments when launching (less secure)

5. Run the MCP server locally using uv (recommended):

uv run --directory PATH/TO/instagram_dm_mcp python src/mcp_server.py

Alternatively, run with Python directly:

python src/mcp_server.py --username YOUR_INSTAGRAM_USERNAME --password YOUR_INSTAGRAM_PASSWORD

6. Connect to Claude Desktop or Cursor and add the instagram_dms MCP server as described in the configuration steps. Restart the MCP client to enable the integration.

Tips and known considerations:

• Environment variables for credentials are preferred for security. Use INSTAGRAM_USERNAME and INSTAGRAM_PASSWORD in a .env file or via the mcp_config env section.
• If you run into authentication issues, ensure you’re using a valid Instagram account and that two-factor authentication is addressed by the login flow in the underlying Instagram client library used by the server.
• The provided tool set supports common DM operations: sending messages (send_message, send_photo_message, send_video_message), listing chats (list_chats, list_pending_chats, search_threads), retrieving thread details (get_thread_details, get_thread_by_participants), and media download capabilities (download_media_from_message, download_shared_post_from_message, list_media_messages).
• For Claude Desktop integration, place the configuration JSON in the specified path and restart the application to load the new MCP server. The same applies to Cursor via its mcp.json location.
• If you switch environments (uv vs direct Python), keep credentials consistent to avoid authentication drift between runs.