Skip to content
Back to search

instagram_dm_mcp

Instagram Direct messages MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/trypeggy--instagram-dm-mcp/badge.svg)](/listings/trypeggy--instagram-dm-mcp)

HTML

<a href="/listings/trypeggy--instagram-dm-mcp"><img src="/api/listings/trypeggy--instagram-dm-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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): ```bash uv sync ``` - Using Pip: ```bash 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 ```json { "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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 210 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Instagram DM MCP server
  2. This is a Model Context Protocol (MCP) server for sending instagram Direct Messages.
  3. With this you can send Instagram Direct Messages from your account (more capabilities coming soon).
  4. Here's an example of what you can do when it's connected to Claude.
  5. https://github.com/user-attachments/assets/9c945f25-4484-4223-8d6b-5bf31243464c
  6. > To get updates on this and other projects we work on [enter your email here](https://tally.so/r/np6rYy)
  7. ---
  8. ## Installation
  9. ### Prerequisites
  10. - Python 3.11+
  11. - Anthropic Claude Desktop app (or Cursor)
  12. - Pip (Python package manager), install with `python -m pip install`
  13. - An instagram account
  14. ### Steps
  15. 1. **Clone this repository**
  16. ```bash
  17. git clone https://github.com/trypeggy/instagram_dm_mcp.git
  18. cd instagram_dm_mcp
  19. ```
  20. 2. **Install dependencies**
  21. - Using uv (recommended):
  22. ```bash
  23. uv sync
  24. ```
  25. - Using Pip:
  26. ```bash
  27. pip install -r requirements.txt
  28. ```
  29. 3. **Configure Instagram credentials**
  30. You have two options for providing your Instagram credentials:
  31. **Option A: Environment Variables (Recommended)**
  32. **Quick Setup (Recommended):**
  33. Run the helper script:
  34. ```bash
  35. python setup_env.py
  36. ```
  37. This will interactively prompt you for your credentials and create the `.env` file securely.
  38. **Manual Setup:**
  39. Create a `.env` file in the project root:
  40. ```bash
  41. cp env.example .env
  42. ```
  43. Then edit `.env` with your actual credentials:
  44. ```
  45. INSTAGRAM_USERNAME=your_instagram_username
  46. INSTAGRAM_PASSWORD=your_instagram_password
  47. ```
  48. **Option B: Command Line Arguments**
  49. You can still pass credentials as command line arguments (less secure).
  50. 4. **Connect to the MCP server**
  51. **For Claude Desktop:**
  52. Save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at:
  53. ```
  54. ~/Library/Application Support/Claude/claude_desktop_config.json
  55. ```
  56. **For Cursor:**
  57. Save this as `mcp.json` in your Cursor configuration directory at:
  58. ```
  59. ~/.cursor/mcp.json
  60. ```
  61. **Configuration with Environment Variables (Recommended):**
  62. - Using uv
  63. ```json
  64. {
  65. "mcpServers": {
  66. "instagram_dms": {
  67. "command": "uv",
  68. "args": [
  69. "run",
  70. "--directory",
  71. "PATH/TO/instagram_dm_mcp",
  72. "python",
  73. "src/mcp_server.py"
  74. ]
  75. }
  76. }
  77. }
  78. ```
  79. - Using Python
  80. ```json
  81. {
  82. "mcpServers": {
  83. "instagram_dms": {
  84. "command": "python",
  85. "args": [
  86. "{{PATH_TO_SRC}}/instagram_dm_mcp/src/ mcp_server.py"
  87. ]
  88. }
  89. }
  90. }
  91. ```
  92. **Configuration with Command Line Arguments:**
  93. ```json
  94. {
  95. "mcpServers": {
  96. "instagram_dms": {
  97. "command": "python",
  98. "args": [
  99. "{{PATH_TO_SRC}}/instagram_dm_mcp/src/mcp_server.py",
  100. "--username",
  101. "{{YOUR_INSTAGRAM_USERNAME}}",
  102. "--password",
  103. "{{YOUR_INSTAGRAM_PASSWORD}}"
  104. ]
  105. }
  106. }
  107. }
  108. ```
  109. 5. **Restart Claude Desktop / Cursor**
  110. Open Claude Desktop and you should now see the Instagram DM MCP as an available integration.
  111. Or restart Cursor.
  112. ---
  113. ## Usage
  114. Below is a list of all available tools and what they do:
  115. | Tool Name | Description |
  116. |-----------------------------|-----------------------------------------------------------------------------------------------|
  117. | `send_message` | Send an Instagram direct message to a user by username. |
  118. | `send_photo_message` | Send a photo as an Instagram direct message to a user by username. |
  119. | `send_video_message` | Send a video as an Instagram direct message to a user by username. |
  120. | `list_chats` | Get Instagram Direct Message threads (chats) from your account, with optional filters/limits. |
  121. | `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. |
  122. | `download_media_from_message` | Download a direct-uploaded photo or video from a DM message (not for shared posts/reels/clips). |
  123. | `download_shared_post_from_message` | Download media from a shared post, reel, or clip in a DM message (not for direct uploads). |
  124. | `list_media_messages` | List all messages containing direct-uploaded media (photo/video) in a DM thread. |
  125. | `mark_message_seen` | Mark a specific message in an Instagram Direct Message thread as seen. |
  126. | `list_pending_chats` | Get Instagram Direct Message threads from your pending inbox. |
  127. | `search_threads` | Search Instagram Direct Message threads by username or keyword. |
  128. | `get_thread_by_participants`| Get an Instagram Direct Message thread by participant user IDs. |
  129. | `get_thread_details` | Get details and messages for a specific Instagram Direct Message thread by thread ID. |
  130. | `get_user_id_from_username` | Get the Instagram user ID for a given username. |
  131. | `get_username_from_user_id` | Get the Instagram username for a given user ID. |
  132. | `get_user_info` | Get information about a specific Instagram user by username. |
  133. | `search_users` | Search for Instagram users by username |
  134. | `get_user_stories` | Get recent stories from a specific Instagram user by username. |
  135. | `like_media` | Like or unlike a specific media post by media ID. |
  136. | `get_user_followers` | Get a list of followers for a specific Instagram user by username. |
  137. | `get_user_following` | Get a list of users that a specific Instagram user is following by username. |
  138. | `get_user_posts` | Get recent posts from a specific Instagram user by username. |
  139. ---
  140. ## Troubleshooting
  141. **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.
  142. For additional Claude Desktop integration troubleshooting, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues). The documentation includes helpful tips for checking logs and resolving common issues.
  143. ---
  144. ## Feedback
  145. Your feedback will be massively appreciated. Please [tell us](mailto:tanmay@usegala.com) which features on that list you like to see next or request entirely new ones.
  146. ---
  147. ## License
  148. This project is licensed under the MIT License.
  149. ![License](https://img.shields.io/badge/license-MIT-blue.svg)
  150. ![Python](https://img.shields.io/badge/python-3.12+-green.svg)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.