mcp-instagram-dm

View on GitHub

mcp-instagram-dm

4 stars JavaScriptOthers Updated Jul 7, 2026

Documentation

⚡ Getting Started

Get up and running in under 60 seconds:

1. Add to your MCP config (Claude Desktop, Claude Code, or Cursor):

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

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

code

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)

bash

npx mcp-instagram-dm

npm global

bash

npm install -g mcp-instagram-dm
mcp-instagram-dm

From source

bash

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

Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

Claude Code

Add to your project's `.mcp.json`:

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:

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

💬 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

code

┌─────────────────────┐     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

Frequently asked questions

What is mcp-instagram-dm?

mcp-instagram-dm is mcp-instagram-dm

How do I install mcp-instagram-dm?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-instagram-dm open source?

Yes — it is hosted on GitHub at https://github.com/0XX7C00/mcp-instagram-dm and has 4 stars.

Related MCP tools

firecrawl-mcp-server

🔥 Official Firecrawl MCP Server - Adds powerful web scraping and search to Cursor, Claude and any other LLM clients.

7,393 JavaScript

batch-processingclaudecontent-extraction+11

deep-research

Use any LLMs (Large Language Models) for Deep Research. Support SSE API and MCP server.

4,684 JavaScript

deep-researchdeepresearchgemini+7

mcp-feedback-enhanced

Enhanced MCP server for interactive user feedback and command execution in AI-assisted development, featuring dual interface support (Web UI and Desktop Application) with intelligent environment detection and cross-platform compatibility.

3,773 JavaScript

papersgpt-for-zotero

A powerful Zotero AI and MCP plugin with ChatGPT, Gemini 3.7, Claude Fable 5, Claude Opus 5, DeepSeek V4, Grok, OpenRouter, Kimi k3, GLM 5.3, SiliconFlow, GPT-oss, Gemma 4, Qwen 3.8

2,625 JavaScript

zoteromistralclaude+17

opendia

Connect your browser to AI models. Just use Dia on Chrome, Arc or Firefox.

1,920 JavaScript

chrome-extensiondiamcp+3

wenyan-mcp

文颜 MCP Server 可以让 AI 自动将 Markdown 文章排版后发布至微信公众号。

1,310 JavaScript

mcp-serverwenyanwechat

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP