mcp-instagram-dm

<div align="center">

📨 MCP Instagram DM

Control your Instagram DMs with AI

Read, send, search, and manage Instagram Direct Messages through natural language with any MCP-compatible AI assistant.

  

    

<br />

A Model Context Protocol server that bridges Instagram Direct Messages with AI assistants like Claude, Cursor, and any MCP-compatible client.

Cookie-based authentication — no API keys, no OAuth, just works.

<br />

Getting Started · Features · Configuration · Tools Reference · Contributing

<br />

💡 If you find this useful, please consider giving it a ⭐ — it helps others discover the project!

</div>

---

⚡ Getting Started

Get up and running in under 60 seconds:

1. Add to your MCP config (Claude Desktop, Claude Code, or Cursor):

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "mcp-instagram-dm"],
      "env": {
        "INSTAGRAM_SESSION_ID": "your_session_id",
        "INSTAGRAM_CSRF_TOKEN": "your_csrf_token",
        "INSTAGRAM_DS_USER_ID": "your_user_id"
      }
    }
  }
}

2. Talk to your AI assistant:

"Read my Instagram DMs"

That's it — you're ready. 🎉

Need help getting your cookies? See Configuration below.

🎬 What It Looks Like

You:    "Show me my unread Instagram DMs"
Claude: Fetching your inbox...

        📬 Inbox (3 conversations)

        [UNREAD] john_doe (thread_id: 340282366841710300...)
          Last: [2026-03-29 14:23:01] john_doe: Hey, are you free tonight?

        [UNREAD] [GROUP] project_team (thread_id: 340282366841710301...)
          Last: [2026-03-29 13:45:22] alice: Meeting moved to 3pm

        jane_smith (thread_id: 340282366841710302...)
          Last: [2026-03-29 10:12:45] You: Thanks! See you then

You:    "Reply to john_doe: Yeah, let's meet at 7!"
Claude: ✅ Message sent: "Yeah, let's meet at 7!"

✨ Features

15 tools across three categories — everything you need to manage your Instagram DMs:

📥 Read & Monitor

| Tool | Description | |---|---| | instagram_get_inbox | List recent DM conversations with unread/group/muted indicators | | instagram_get_thread | Get messages from a conversation (auto-paginates — fetch 500+ messages at once) | | instagram_get_pending | List pending DM requests waiting for your approval | | instagram_user_info | Get any user's profile: bio, followers, posts, verification | | instagram_thread_info | Thread metadata: participants, group info, mute/archive status |

✏️ Send & Manage

| Tool | Description | |---|---| | instagram_send_message | Send a text message in any thread | | instagram_send_link | Share a URL with optional caption | | instagram_create_thread | Start a new DM with one or multiple users | | instagram_like_message | React to any message with any emoji | | instagram_unsend_message | Unsend your own messages | | instagram_mark_seen | Mark a conversation as read | | instagram_approve_pending | Approve a pending DM request |

🔍 Search & Discover

| Tool | Description | |---|---| | instagram_search_inbox | Search conversations by username or name (scans all pages) | | instagram_search_messages | Find messages containing specific text within a thread | | instagram_search_users | Search Instagram users to start new conversations |

📦 Installation

npx (recommended — zero install)

npx mcp-instagram-dm

npm global

npm install -g mcp-instagram-dm
mcp-instagram-dm

From source

git clone https://github.com/KynuxDev/mcp-instagram-dm.git
cd mcp-instagram-dm
npm install && npm run build
node dist/index.js

🔧 Configuration

Getting Your Cookies

1. Open instagram.com in Chrome and log in
2. Press F12 → Application tab → Cookies → https://www.instagram.com
3. Copy these three values:

| Cookie Name | Environment Variable | Description | |---|---|---| | sessionid | INSTAGRAM_SESSION_ID | Your session token | | csrftoken | INSTAGRAM_CSRF_TOKEN | CSRF protection token | | ds_user_id | INSTAGRAM_DS_USER_ID | Your numeric user ID |

💡 Tip: You can also run node get-cookies.js for a guided walkthrough.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | INSTAGRAM_SESSION_ID | ✅ | — | Your Instagram session cookie | | INSTAGRAM_CSRF_TOKEN | ✅ | — | CSRF token from cookies | | INSTAGRAM_DS_USER_ID | ✅ | — | Your numeric user ID | | INSTAGRAM_RATE_LIMIT_MS | — | 300 | Delay between paginated API requests (ms) |

Client Setup

<details> <summary><b>Claude Desktop</b></summary> <br />

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "mcp-instagram-dm"],
      "env": {
        "INSTAGRAM_SESSION_ID": "your_session_id",
        "INSTAGRAM_CSRF_TOKEN": "your_csrf_token",
        "INSTAGRAM_DS_USER_ID": "your_user_id"
      }
    }
  }
}

</details>

<details> <summary><b>Claude Code</b></summary> <br />

Add to your project's .mcp.json:

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "mcp-instagram-dm"],
      "env": {
        "INSTAGRAM_SESSION_ID": "your_session_id",
        "INSTAGRAM_CSRF_TOKEN": "your_csrf_token",
        "INSTAGRAM_DS_USER_ID": "your_user_id"
      }
    }
  }
}

</details>

<details> <summary><b>Cursor</b></summary> <br />

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "mcp-instagram-dm"],
      "env": {
        "INSTAGRAM_SESSION_ID": "your_session_id",
        "INSTAGRAM_CSRF_TOKEN": "your_csrf_token",
        "INSTAGRAM_DS_USER_ID": "your_user_id"
      }
    }
  }
}

</details>

💬 Usage Examples

Just talk naturally to your AI assistant:

| What you say | What happens | |---|---| | "Read my unread Instagram DMs" | Fetches inbox with unread indicators | | "Send 'Hey!' to @username" | Finds the thread and sends the message | | "Search my DMs for messages about 'meeting'" | Scans thread messages for the keyword | | "Start a new conversation with @johndoe" | Creates a new thread and sends your message | | "Show me pending DM requests and approve them" | Lists and approves pending requests | | "What's @user's profile info?" | Fetches full profile details | | "Get the last 200 messages with @friend" | Auto-paginates to fetch all messages | | "React with 🔥 to the last message" | Sends emoji reaction to any message |

📖 Tools Reference

<details> <summary><b>View all 15 tools with parameters</b></summary> <br />

| Tool | Description | Parameters | |---|---|---| | instagram_get_inbox | List DM conversations | limit?, cursor? | | instagram_get_thread | Get thread messages (auto-paginates) | thread_id, limit?, cursor? | | instagram_get_pending | List pending requests | limit?, cursor? | | instagram_user_info | Get user profile | user_id | | instagram_thread_info | Get thread details | thread_id | | instagram_send_message | Send text message | thread_id, text | | instagram_send_link | Share a URL | thread_id, url, text? | | instagram_create_thread | Start new DM | recipient_ids[], text | | instagram_like_message | React with emoji | thread_id, item_id, emoji? | | instagram_unsend_message | Unsend a message | thread_id, item_id | | instagram_mark_seen | Mark as read | thread_id, item_id | | instagram_approve_pending | Approve request | thread_id | | instagram_search_inbox | Search conversations | query, max_pages? | | instagram_search_messages | Search within thread | thread_id, query, max_messages? | | instagram_search_users | Find users | query |

</details>

🏗️ Architecture

┌─────────────────────┐     MCP (stdio)     ┌──────────────────────┐
│   AI Assistant       │◄──────────────────►│   MCP Server          │
│   (Claude, Cursor)   │                     │   src/index.ts        │
└─────────────────────┘                     │   15 tools            │
                                             └──────────┬───────────┘
                                                        │
                                             ┌──────────▼───────────┐
                                             │   Instagram Client    │
                                             │   src/instagram.ts    │
                                             │   Cookie auth + HTTP  │
                                             └──────────┬───────────┘
                                                        │
                                             ┌──────────▼───────────┐
                                             │   Instagram Web API   │
                                             │   (Private endpoints) │
                                             └──────────────────────┘

Design principles:

• Single dependency — only @modelcontextprotocol/sdk. No axios, no puppeteer, no bloat.
• TypeScript strict — zero any types, fully typed interfaces in src/types.ts
• Auto-pagination — request 500 messages and the server handles the rest with rate limiting
• 14+ message types — text, media, voice, reels, links, clips, GIFs, posts, stories, and more

🔒 Security

• Session cookies are never logged or stored beyond runtime
• All credentials are read from environment variables only
• No data is sent to any third-party service
• See SECURITY.md for reporting vulnerabilities

⚠️ Disclaimer

This project uses Instagram's unofficial web API, which may change without notice.

• Personal use only — do not use for spam, mass messaging, or automation that violates Instagram's Terms of Service
• Your session cookies are sensitive credentials — never share or commit them
• This project is not affiliated with, endorsed by, or connected to Meta or Instagram
• Use at your own risk — the authors are not responsible for any account restrictions

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup and guidelines.

If you'd like to support the project financially, consider sponsoring on GitHub.

📄 License

MIT — Made with ❤️ by Kynux

---

<div align="center">

If this project helped you, consider giving it a ⭐

Report Bug · Request Feature · Contribute

</div>