Summary
This server bridges Instagram Direct Messages to MCP clients using cookie-based authentication. It exposes 15 tools split across reading (get_inbox, get_thread with auto-pagination, get_pending), sending (send_message, send_link, create_thread, like_message, unsend_message), and searching (search_inbox, search_messages, search_users). You authenticate with sessionid, csrftoken, and ds_user_id cookies extracted from your browser. Reach for this when you want to triage DMs, search conversation history, or send replies without context switching from Claude Desktop or Cursor. The auto-pagination on get_thread means you can pull hundreds of messages in one call. It talks directly to Instagram's private API, so no official keys or OAuth flows required.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
📨 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)
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.jsfor 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 |
📖 Tools Reference
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
anytypes, fully typed interfaces insrc/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
If this project helped you, consider giving it a ⭐
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Registryactive
Packagemcp-instagram-dm
TransportSTDIO
UpdatedApr 4, 2026
