Which integrations are available for this server?

Allows AI assistants to read, send, search, and manage Instagram Direct Messages. Provides tools for inbox management, thread operations, message sending, user searches, and conversation monitoring including pending requests and message reactions.

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

License: MIT Node.js TypeScript MCP

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.

Getting Started · Features · Configuration · Tools Reference · Contributing

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

⚡ 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

Open instagram.com in Chrome and log in
Press F12 → Application tab → Cookies → https://www.instagram.com
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

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

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

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

💬 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

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`

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

If this project helped you, consider giving it a ⭐

Report Bug · Request Feature · Contribute

mcp-instagram-dm