mcp-instagram-dm

★ 3

from KynuxDev

Read, send, search, and manage Instagram DMs through AI assistants via MCP. 15 tools, cookie-based auth, single dependency.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys

#automation #social-media #scraping #git #security #video-editing

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

🎬 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

📖 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

If this project helped you, consider giving it a ⭐

Report Bug · Request Feature · Contribute

</div>

Copy & paste — that's it

npx mcp-instagram-dm

Before it works, you'll need: INSTAGRAM_SESSION_IDINSTAGRAM_CSRF_TOKENINSTAGRAM_DS_USER_ID

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

📦 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

<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