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