# mcp-instagram-dm

**Category:** 🌐 Social Media  
**Repository:** https://github.com/KynuxDev/mcp-instagram-dm  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-instagram-dm

## Description
Read, send, search & manage Instagram DMs through AI assistants. 15 tools, cookie auth.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "mcp-instagram-dm": {
    "command": "npx",
    "args": ["-y","mcp-instagram-dm"]
  }
}
```

## Documentation & README

<div align="center">

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

[![npm version](https://img.shields.io/npm/v/mcp-instagram-dm.svg?style=for-the-badge&color=CB3837&logo=npm)](https://www.npmjs.com/package/mcp-instagram-dm)
[![npm downloads](https://img.shields.io/npm/dm/mcp-instagram-dm.svg?style=for-the-badge&color=blue&logo=npm)](https://www.npmjs.com/package/mcp-instagram-dm)
[![GitHub stars](https://img.shields.io/github/stars/KynuxDev/mcp-instagram-dm?style=for-the-badge&color=gold&logo=github)](https://github.com/KynuxDev/mcp-instagram-dm/stargazers)

[![CI](https://img.shields.io/github/actions/workflow/status/KynuxDev/mcp-instagram-dm/ci.yml?style=flat-square&label=CI&logo=githubactions&logoColor=white)](https://github.com/KynuxDev/mcp-instagram-dm/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io)

<br />

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.

<br />

[Getting Started](#-getting-started) · [Features](#-features) · [Configuration](#-configuration) · [Tools Reference](#-tools-reference) · [Contributing](#-contributing)

<br />

> **💡 If you find this useful, please consider giving it a ⭐ — it helps others discover the project!**

</div>

---

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

<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):

```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>Claude Code</b></summary>
<br />

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"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>
<br />

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

## 📖 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](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)

---

<div align="center">

**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)

</div>