# ๐จ 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.
[](https://www.npmjs.com/package/mcp-instagram-dm)
[](https://www.npmjs.com/package/mcp-instagram-dm)
[](https://github.com/KynuxDev/mcp-instagram-dm/stargazers)
[](https://github.com/KynuxDev/mcp-instagram-dm/actions)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io)
A [Model Context Protocol](https://modelcontextprotocol.io) 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](#-getting-started) ยท [Features](#-features) ยท [Configuration](#-configuration) ยท [Tools Reference](#-tools-reference) ยท [Contributing](#-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):
```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](#-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)
```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](https://www.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
```
โโโโโโโโโโโโโโโโโโโโโโโ 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](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](https://help.instagram.com/581066165581870)
- 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](CONTRIBUTING.md) for development setup and guidelines.
If you'd like to support the project financially, consider [sponsoring on GitHub](https://github.com/sponsors/KynuxDev).
## ๐ License
[MIT](LICENSE) โ Made with โค๏ธ by [Kynux](https://github.com/KynuxDev)
---
**If this project helped you, consider giving it a โญ**
[Report Bug](https://github.com/KynuxDev/mcp-instagram-dm/issues/new?template=bug_report.md) ยท [Request Feature](https://github.com/KynuxDev/mcp-instagram-dm/issues/new?template=feature_request.md) ยท [Contribute](CONTRIBUTING.md)