📨 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.
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)
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
Claude Desktop
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"
}
}
}
}
Claude Code
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"
}
}
}
}
Cursor
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 |
View all 15 tools with parameters
| 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
