mcp-instagram-dm 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kynux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# mcp-instagram-dm
+
+[![npm version](https://img.shields.io/npm/v/mcp-instagram-dm.svg)](https://www.npmjs.com/package/mcp-instagram-dm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+Read, send, and manage Instagram Direct Messages through AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Works with **personal Instagram accounts** using cookie-based authentication. Supports reading conversations, sending messages, reacting, searching, and more — all through natural language with your AI assistant.
+
+## Quick Start
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config:
+
+```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"
+      }
+    }
+  }
+}
+```
+
+That's it. Ask Claude: *"Read my Instagram DMs"* and it works.
+
+## Features
+
+### Read
+- **`instagram_get_inbox`** — List recent DM conversations with unread indicators
+- **`instagram_get_thread`** — Get messages from a conversation (auto-paginates, e.g. fetch 500 messages at once)
+- **`instagram_get_pending`** — List pending DM requests
+- **`instagram_user_info`** — Get a user's profile details (bio, followers, posts)
+- **`instagram_thread_info`** — Get conversation metadata (participants, group info, mute status)
+
+### Write
+- **`instagram_send_message`** — Send a text message
+- **`instagram_send_link`** — Share a URL in a conversation
+- **`instagram_create_thread`** — Start a new DM with any user
+- **`instagram_like_message`** — React to a 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
+- **`instagram_search_inbox`** — Search conversations by username or name
+- **`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](https://www.instagram.com) in Chrome and log in
+2. Press **F12** to open DevTools
+3. Go to **Application** tab > **Cookies** > `https://www.instagram.com`
+4. Copy these values:
+
+| Cookie Name | Environment Variable |
+|---|---|
+| `sessionid` | `INSTAGRAM_SESSION_ID` |
+| `csrftoken` | `INSTAGRAM_CSRF_TOKEN` |
+| `ds_user_id` | `INSTAGRAM_DS_USER_ID` |
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `INSTAGRAM_SESSION_ID` | Yes | Your Instagram session cookie |
+| `INSTAGRAM_CSRF_TOKEN` | Yes | CSRF token from cookies |
+| `INSTAGRAM_DS_USER_ID` | Yes | Your numeric user ID |
+| `INSTAGRAM_RATE_LIMIT_MS` | No | Delay between paginated requests (default: 300ms) |
+
+### Client Configuration
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+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>
+
+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>
+
+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>
+
+## Examples
+
+Just talk to your AI assistant naturally:
+
+- *"Read my unread Instagram DMs"*
+- *"Send 'Hey, are you free tonight?' to my conversation with @username"*
+- *"Search my DMs for messages about 'meeting'"*
+- *"Start a new conversation with @johndoe and say hello"*
+- *"Show me my pending DM requests and approve them"*
+- *"Get the profile info for user 12345678"*
+
+## Tools Reference
+
+| Tool | Description | Key Parameters |
+|---|---|---|
+| `instagram_get_inbox` | List DM conversations | `limit`, `cursor` |
+| `instagram_get_thread` | Get thread messages | `thread_id`, `limit` (auto-paginates) |
+| `instagram_get_pending` | List pending requests | `limit`, `cursor` |
+| `instagram_user_info` | Get user profile | `user_id` (PK) |
+| `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` |
+
+## How It Works
+
+This server uses Instagram's private web API (the same API the instagram.com website uses) with cookie-based authentication. It communicates with AI assistants through the Model Context Protocol (MCP) via stdio transport.
+
+**Architecture:**
+- `src/index.ts` — MCP server with 15 tools
+- `src/instagram.ts` — Instagram API client
+- `src/types.ts` — TypeScript interfaces
+
+**Single dependency:** Only `@modelcontextprotocol/sdk`. No axios, no puppeteer, no bloat.
+
+## 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 them or commit them to version control
+- 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 guidelines.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const instagram_js_1 = require("./instagram.js");
+const ig = new instagram_js_1.InstagramClient();
+// --- Helpers ---
+function buildUserMap(thread) {
+    const map = new Map();
+    for (const u of thread.users ?? []) {
+        map.set(String(u.pk), u.username);
+    }
+    if (ig.viewerUsername) {
+        const viewerId = process.env.INSTAGRAM_DS_USER_ID || "";
+        if (viewerId)
+            map.set(viewerId, ig.viewerUsername);
+    }
+    return map;
+}
+function formatMessage(item, users) {
+    const sender = users.get(String(item.user_id)) ?? String(item.user_id);
+    const date = new Date(item.timestamp / 1000).toISOString().replace("T", " ").slice(0, 19);
+    let content;
+    switch (item.item_type) {
+        case "text":
+            content = item.text ?? "";
+            break;
+        case "media":
+            content = "[Media]";
+            if (item.media?.image_versions2?.candidates?.[0]?.url) {
+                content += ` ${item.media.image_versions2.candidates[0].url.split("?")[0]}`;
+            }
+            break;
+        case "voice_media":
+            content = "[Voice message]";
+            if (item.voice_media?.media?.audio?.audio_src) {
+                content += ` ${item.voice_media.media.audio.audio_src.split("?")[0]}`;
+            }
+            break;
+        case "reel_share":
+            content = `[Reel] ${item.reel_share?.text ?? ""}`;
+            break;
+        case "link":
+            content = `[Link] ${item.link?.text ?? ""} ${item.link?.link_url ?? ""}`.trim();
+            break;
+        case "clip":
+            content = `[Clip] ${item.clip?.clip?.caption?.text ?? ""}`;
+            break;
+        case "animated_media":
+            content = "[GIF]";
+            if (item.animated_media?.images?.fixed_height?.url) {
+                content += ` ${item.animated_media.images.fixed_height.url.split("?")[0]}`;
+            }
+            break;
+        case "media_share":
+            content = `[Post share] ${item.media_share?.caption?.text ?? ""}`.trim();
+            break;
+        case "story_share":
+            content = `[Story share] ${item.story_share?.title ?? ""} ${item.story_share?.message ?? ""}`.trim();
+            break;
+        case "action_log":
+            content = `[${item.action_log?.description ?? "Action"}]`;
+            break;
+        default:
+            content = `[${item.item_type}]`;
+    }
+    if (item.reply_to_message?.text) {
+        content = `(reply: "${item.reply_to_message.text.slice(0, 50)}") ${content}`;
+    }
+    if (item.reactions?.emojis?.length) {
+        const reacts = item.reactions.emojis.map((r) => r.emoji).join("");
+        content += ` ${reacts}`;
+    }
+    return `[${date}] ${sender}: ${content}`;
+}
+function formatThread(t) {
+    const users = t.users?.map((u) => u.username).join(", ") || "";
+    const title = t.thread_title || users;
+    const userMap = buildUserMap(t);
+    const lastItem = t.items?.[0];
+    const lastText = lastItem ? formatMessage(lastItem, userMap) : "(empty)";
+    const unread = t.read_state === 0 ? " [UNREAD]" : "";
+    const group = t.is_group ? " [GROUP]" : "";
+    const muted = t.muted ? " [MUTED]" : "";
+    const pending = t.pending ? " [PENDING]" : "";
+    return `${unread}${group}${muted}${pending} ${title} (thread_id: ${t.thread_id})\n  Last: ${lastText}`;
+}
+function formatUserInfo(user) {
+    const parts = [
+        `User: @${user.username}`,
+        `Name: ${user.full_name || "-"}`,
+        user.is_verified ? "Verified" : null,
+        user.is_private ? "Private account" : "Public account",
+        user.biography ? `Bio: ${user.biography}` : null,
+        user.follower_count != null ? `Followers: ${user.follower_count}` : null,
+        user.following_count != null ? `Following: ${user.following_count}` : null,
+        user.media_count != null ? `Posts: ${user.media_count}` : null,
+        user.external_url ? `Link: ${user.external_url}` : null,
+        `PK: ${user.pk}`,
+    ];
+    return parts.filter(Boolean).join("\n");
+}
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function err(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+}
+// --- MCP Server ---
+const server = new mcp_js_1.McpServer({ name: "instagram-dm", version: "2.1.0" });
+// ===== 1. INBOX =====
+server.tool("instagram_get_inbox", "List recent Instagram DM conversations", {
+    cursor: zod_1.z.string().optional().describe("Pagination cursor from previous response"),
+    limit: zod_1.z.number().optional().default(20).describe("Number of conversations to fetch (max 20)"),
+}, async ({ cursor, limit }) => {
+    try {
+        const data = await ig.getInbox(cursor, limit);
+        const threads = (data.inbox?.threads || []).map(formatThread).join("\n\n");
+        const pendingCount = data.pending_requests_total ?? 0;
+        const pendingInfo = pendingCount > 0 ? `\nPending requests: ${pendingCount}` : "";
+        const footer = data.inbox?.has_older
+            ? `\n\n--- More: cursor="${data.inbox.oldest_cursor}" ---`
+            : "\n\n--- End ---";
+        return ok(`Inbox (${data.inbox?.threads?.length || 0})${pendingInfo}\n\n${threads}${footer}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 2. THREAD =====
+server.tool("instagram_get_thread", "Get messages from a specific DM conversation. Automatically paginates when limit > 20 (e.g. limit=500 fetches 500 messages at once).", {
+    thread_id: zod_1.z.string().describe("Thread ID (from inbox)"),
+    cursor: zod_1.z.string().optional().describe("Pagination cursor"),
+    limit: zod_1.z.number().optional().default(20).describe("Number of messages to fetch (auto-paginates above 20, e.g. 500)"),
+}, async ({ thread_id, cursor, limit }) => {
+    try {
+        const allItems = [];
+        let userMap = new Map();
+        let title = "";
+        let currentCursor = cursor;
+        let hasOlder = true;
+        let oldestCursor = "";
+        const perPage = 20;
+        while (allItems.length < limit && hasOlder) {
+            const fetchLimit = Math.min(perPage, limit - allItems.length);
+            const data = await ig.getThread(thread_id, currentCursor, fetchLimit);
+            const t = data.thread;
+            if (!title) {
+                title = t.thread_title || t.users?.map((u) => u.username).join(", ");
+                userMap = buildUserMap(t);
+            }
+            const items = t.items || [];
+            if (items.length === 0)
+                break;
+            allItems.push(...items);
+            hasOlder = !!t.has_older;
+            oldestCursor = t.oldest_cursor || "";
+            currentCursor = oldestCursor;
+            if (allItems.length < limit && hasOlder) {
+                await new Promise((r) => setTimeout(r, 300));
+            }
+        }
+        const messages = [...allItems]
+            .reverse()
+            .map((item) => formatMessage(item, userMap))
+            .join("\n");
+        const footer = hasOlder
+            ? `\n\n--- Older messages: cursor="${oldestCursor}" ---`
+            : "\n\n--- Start ---";
+        return ok(`${title} (${allItems.length} messages)\n\n${messages}${footer}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 3. SEARCH =====
+server.tool("instagram_search_inbox", "Search inbox by username or name (scans all pages)", {
+    query: zod_1.z.string().describe("Username or name to search"),
+    max_pages: zod_1.z.number().optional().default(5).describe("Max pages to scan (20 threads per page)"),
+}, async ({ query, max_pages }) => {
+    try {
+        const q = query.toLowerCase();
+        const matched = [];
+        let cursor;
+        let pages = 0;
+        while (pages < max_pages) {
+            const data = await ig.getInbox(cursor, 20);
+            const threads = data.inbox?.threads || [];
+            for (const t of threads) {
+                if (t.thread_title?.toLowerCase().includes(q)) {
+                    matched.push(t);
+                    continue;
+                }
+                if (t.users?.some((u) => u.username.toLowerCase().includes(q) || u.full_name?.toLowerCase().includes(q))) {
+                    matched.push(t);
+                }
+            }
+            if (!data.inbox?.has_older)
+                break;
+            cursor = data.inbox.oldest_cursor;
+            pages++;
+        }
+        if (!matched.length) {
+            return ok(`"${query}" not found. (${pages + 1} pages scanned)`);
+        }
+        return ok(`"${query}" - ${matched.length} result(s) (${pages + 1} pages scanned)\n\n${matched.map(formatThread).join("\n\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 4. SEND MESSAGE =====
+server.tool("instagram_send_message", "Send a text message in an Instagram DM thread", {
+    thread_id: zod_1.z.string().describe("Thread ID"),
+    text: zod_1.z.string().describe("Message text to send"),
+}, async ({ thread_id, text }) => {
+    try {
+        await ig.sendMessage(thread_id, text);
+        return ok(`Message sent: "${text.slice(0, 100)}${text.length > 100 ? "..." : ""}"`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 5. SEND LINK =====
+server.tool("instagram_send_link", "Share a link in an Instagram DM thread", {
+    thread_id: zod_1.z.string().describe("Thread ID"),
+    url: zod_1.z.string().describe("URL to share"),
+    text: zod_1.z.string().optional().describe("Optional text to send with the link"),
+}, async ({ thread_id, url, text }) => {
+    try {
+        await ig.sendLink(thread_id, url, text);
+        return ok(`Link sent: ${url}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 6. REACT =====
+server.tool("instagram_like_message", "React to a message with an emoji (default: heart)", {
+    thread_id: zod_1.z.string().describe("Thread ID"),
+    item_id: zod_1.z.string().describe("Message ID"),
+    emoji: zod_1.z.string().optional().default("\u2764\uFE0F").describe("Reaction emoji (default: heart)"),
+}, async ({ thread_id, item_id, emoji }) => {
+    try {
+        await ig.reactToMessage(thread_id, item_id, emoji);
+        return ok(`Reaction sent: ${emoji}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 7. UNSEND =====
+server.tool("instagram_unsend_message", "Unsend a message you sent (your own messages only)", {
+    thread_id: zod_1.z.string().describe("Thread ID"),
+    item_id: zod_1.z.string().describe("Message ID to unsend"),
+}, async ({ thread_id, item_id }) => {
+    try {
+        await ig.unsendMessage(thread_id, item_id);
+        return ok("Message unsent.");
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 8. MARK SEEN =====
+server.tool("instagram_mark_seen", "Mark a conversation as read", {
+    thread_id: zod_1.z.string().describe("Thread ID"),
+    item_id: zod_1.z.string().describe("Last seen message ID"),
+}, async ({ thread_id, item_id }) => {
+    try {
+        await ig.markSeen(thread_id, item_id);
+        return ok("Marked as seen.");
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 9. PENDING INBOX =====
+server.tool("instagram_get_pending", "List pending (unapproved) DM requests", {
+    cursor: zod_1.z.string().optional().describe("Pagination cursor"),
+    limit: zod_1.z.number().optional().default(20).describe("Number of requests to fetch"),
+}, async ({ cursor, limit }) => {
+    try {
+        const data = await ig.getPendingInbox(cursor, limit);
+        const threads = (data.inbox?.threads || []).map(formatThread).join("\n\n");
+        const footer = data.inbox?.has_older
+            ? `\n\n--- More: cursor="${data.inbox.oldest_cursor}" ---`
+            : "\n\n--- End ---";
+        return ok(`Pending requests (${data.inbox?.threads?.length || 0})\n\n${threads}${footer}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 10. APPROVE PENDING =====
+server.tool("instagram_approve_pending", "Approve a pending DM request", {
+    thread_id: zod_1.z.string().describe("Thread ID to approve"),
+}, async ({ thread_id }) => {
+    try {
+        await ig.approvePending(thread_id);
+        return ok("Request approved.");
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 11. USER INFO =====
+server.tool("instagram_user_info", "Get a user's profile information", {
+    user_id: zod_1.z.string().describe("User PK ID (from thread user list)"),
+}, async ({ user_id }) => {
+    try {
+        const data = await ig.getUserInfo(user_id);
+        return ok(formatUserInfo(data.user));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 12. SEARCH USERS =====
+server.tool("instagram_search_users", "Search Instagram users (useful for finding users to message)", {
+    query: zod_1.z.string().describe("Username or name to search"),
+}, async ({ query }) => {
+    try {
+        const data = await ig.searchUsers(query);
+        const recipients = data.ranked_recipients || [];
+        if (!recipients.length) {
+            return ok(`No results for "${query}".`);
+        }
+        const lines = recipients
+            .filter((r) => r.user)
+            .map((r) => {
+            const u = r.user;
+            return `@${u.username} - ${u.full_name || ""} (pk: ${u.pk})${u.is_verified ? " [Verified]" : ""}`;
+        })
+            .join("\n");
+        const threads = recipients
+            .filter((r) => r.thread)
+            .map((r) => {
+            const t = r.thread;
+            return `[Thread] ${t.thread_title || "Unnamed"} (thread_id: ${t.thread_id})`;
+        })
+            .join("\n");
+        let result = `Results for "${query}":\n\n`;
+        if (lines)
+            result += `Users:\n${lines}\n`;
+        if (threads)
+            result += `\nExisting threads:\n${threads}\n`;
+        return ok(result);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 13. CREATE THREAD =====
+server.tool("instagram_create_thread", "Start a new DM conversation by sending a message to one or more users", {
+    recipient_ids: zod_1.z.array(zod_1.z.string()).describe("User PK IDs (use instagram_search_users to find)"),
+    text: zod_1.z.string().describe("Initial message text"),
+}, async ({ recipient_ids, text }) => {
+    try {
+        const data = await ig.createThread(recipient_ids, text);
+        const threadId = data.payload?.thread_id || data.thread_id || "unknown";
+        return ok(`Thread created (thread_id: ${threadId}). Message sent: "${text.slice(0, 100)}${text.length > 100 ? "..." : ""}"`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 14. SEARCH MESSAGES =====
+server.tool("instagram_search_messages", "Search for messages containing specific text within a DM thread", {
+    thread_id: zod_1.z.string().describe("Thread ID to search in"),
+    query: zod_1.z.string().describe("Text to search for"),
+    max_messages: zod_1.z.number().optional().default(200).describe("Max messages to scan (default 200)"),
+}, async ({ thread_id, query, max_messages }) => {
+    try {
+        const q = query.toLowerCase();
+        const allItems = [];
+        let userMap = new Map();
+        let title = "";
+        let currentCursor;
+        let hasOlder = true;
+        while (allItems.length < max_messages && hasOlder) {
+            const data = await ig.getThread(thread_id, currentCursor, 20);
+            const t = data.thread;
+            if (!title) {
+                title = t.thread_title || t.users?.map((u) => u.username).join(", ");
+                userMap = buildUserMap(t);
+            }
+            const items = t.items || [];
+            if (items.length === 0)
+                break;
+            allItems.push(...items);
+            hasOlder = !!t.has_older;
+            currentCursor = t.oldest_cursor || "";
+            if (allItems.length < max_messages && hasOlder) {
+                await new Promise((r) => setTimeout(r, 300));
+            }
+        }
+        const matches = allItems
+            .filter((item) => {
+            const text = item.text?.toLowerCase() || "";
+            const reel = item.reel_share?.text?.toLowerCase() || "";
+            const link = item.link?.text?.toLowerCase() || "";
+            const clip = item.clip?.clip?.caption?.text?.toLowerCase() || "";
+            const share = item.media_share?.caption?.text?.toLowerCase() || "";
+            return text.includes(q) || reel.includes(q) || link.includes(q) || clip.includes(q) || share.includes(q);
+        })
+            .reverse()
+            .map((item) => formatMessage(item, userMap));
+        if (!matches.length) {
+            return ok(`No messages matching "${query}" in ${title}. (${allItems.length} messages scanned)`);
+        }
+        return ok(`Found ${matches.length} message(s) matching "${query}" in ${title} (${allItems.length} scanned):\n\n${matches.join("\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ===== 15. THREAD INFO =====
+server.tool("instagram_thread_info", "Get conversation details: participants, group name, mute status, and more", {
+    thread_id: zod_1.z.string().describe("Thread ID"),
+}, async ({ thread_id }) => {
+    try {
+        const data = await ig.getThread(thread_id, undefined, 1);
+        const t = data.thread;
+        const participants = t.users?.map((u) => `@${u.username} (${u.full_name || "-"}, pk: ${u.pk})${u.is_verified ? " [Verified]" : ""}`).join("\n  ") || "None";
+        const parts = [
+            `Thread: ${t.thread_title || t.users?.map((u) => u.username).join(", ") || "Unnamed"}`,
+            `Thread ID: ${t.thread_id}`,
+            `Type: ${t.is_group ? "Group" : "Direct"}`,
+            `Participants:\n  ${participants}`,
+            `Muted: ${t.muted ? "Yes" : "No"}`,
+            `Archived: ${t.archived ? "Yes" : "No"}`,
+            `Pending: ${t.pending ? "Yes" : "No"}`,
+            `Has older messages: ${t.has_older ? "Yes" : "No"}`,
+            t.inviter ? `Inviter: @${t.inviter.username}` : null,
+        ];
+        return ok(parts.filter(Boolean).join("\n"));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// --- Start ---
+async function main() {
+    await ig.validateSession();
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});

package/dist/instagram.d.ts

@@ -0,0 +1,23 @@
+import type { InstaInboxResponse, InstaThreadResponse, InstaUserInfoResponse, InstaActionResponse, InstaSearchUsersResponse } from "./types.js";
+export declare class InstagramClient {
+    private sessionId;
+    private csrfToken;
+    private dsUserId;
+    viewerUsername: string;
+    constructor();
+    private get headers();
+    private request;
+    validateSession(): Promise<void>;
+    getInbox(cursor?: string, limit?: number): Promise<InstaInboxResponse>;
+    getThread(threadId: string, cursor?: string, limit?: number): Promise<InstaThreadResponse>;
+    getPendingInbox(cursor?: string, limit?: number): Promise<InstaInboxResponse>;
+    getUserInfo(userId: string): Promise<InstaUserInfoResponse>;
+    sendMessage(threadId: string, text: string): Promise<InstaActionResponse>;
+    sendLink(threadId: string, linkUrl: string, text?: string): Promise<InstaActionResponse>;
+    reactToMessage(threadId: string, itemId: string, emoji?: string): Promise<InstaActionResponse>;
+    unsendMessage(threadId: string, itemId: string): Promise<InstaActionResponse>;
+    markSeen(threadId: string, itemId: string): Promise<InstaActionResponse>;
+    approvePending(threadId: string): Promise<InstaActionResponse>;
+    searchUsers(query: string): Promise<InstaSearchUsersResponse>;
+    createThread(recipientIds: string[], text: string): Promise<InstaActionResponse>;
+}

package/dist/instagram.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstagramClient = void 0;
+const IG_APP_ID = "936619743392459";
+const RATE_LIMIT_MS = parseInt(process.env.INSTAGRAM_RATE_LIMIT_MS || "300", 10);
+const ERROR_TRUNCATE = 500;
+const DEFAULT_PAGE_SIZE = 20;
+class InstagramClient {
+    sessionId;
+    csrfToken;
+    dsUserId;
+    viewerUsername = "";
+    constructor() {
+        this.sessionId = process.env.INSTAGRAM_SESSION_ID || "";
+        this.csrfToken = process.env.INSTAGRAM_CSRF_TOKEN || "";
+        this.dsUserId = process.env.INSTAGRAM_DS_USER_ID || "";
+        if (!this.sessionId || !this.csrfToken || !this.dsUserId) {
+            throw new Error("Missing Instagram credentials. Required env variables: INSTAGRAM_SESSION_ID, INSTAGRAM_CSRF_TOKEN, INSTAGRAM_DS_USER_ID");
+        }
+    }
+    get headers() {
+        return {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+            "X-CSRFToken": this.csrfToken,
+            "X-IG-App-ID": IG_APP_ID,
+            "X-Requested-With": "XMLHttpRequest",
+            Referer: "https://www.instagram.com/direct/inbox/",
+            Cookie: `sessionid=${this.sessionId}; csrftoken=${this.csrfToken}; ds_user_id=${this.dsUserId}`,
+        };
+    }
+    async request(path, params, method = "GET", body) {
+        const url = new URL(path, "https://www.instagram.com");
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        const opts = {
+            method,
+            headers: this.headers,
+        };
+        if (body && method === "POST") {
+            const formBody = new URLSearchParams(body).toString();
+            opts.body = formBody;
+            opts.headers["Content-Type"] =
+                "application/x-www-form-urlencoded";
+        }
+        const res = await fetch(url.toString(), opts);
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Instagram API error: ${res.status} ${res.statusText} - ${text.slice(0, ERROR_TRUNCATE)}`);
+        }
+        const text = await res.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`JSON parse error. Response (first ${ERROR_TRUNCATE} chars): ${text.slice(0, ERROR_TRUNCATE)}`);
+        }
+    }
+    // --- Session Validation ---
+    async validateSession() {
+        try {
+            await this.request("/api/v1/direct_v2/inbox/", {
+                limit: "1",
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("401") || msg.includes("403") || msg.includes("login")) {
+                throw new Error("Instagram session expired or invalid. Please update your cookies (INSTAGRAM_SESSION_ID, INSTAGRAM_CSRF_TOKEN, INSTAGRAM_DS_USER_ID).");
+            }
+            throw e;
+        }
+    }
+    // --- READ ---
+    async getInbox(cursor, limit = DEFAULT_PAGE_SIZE) {
+        const params = {
+            visual_message_return_type: "unseen",
+            thread_message_limit: "1",
+            persistentBadging: "true",
+            limit: String(limit),
+        };
+        if (cursor)
+            params.cursor = cursor;
+        const data = await this.request("/api/v1/direct_v2/inbox/", params);
+        if (data.viewer?.username && !this.viewerUsername) {
+            this.viewerUsername = data.viewer.username;
+        }
+        return data;
+    }
+    async getThread(threadId, cursor, limit = DEFAULT_PAGE_SIZE) {
+        const params = {
+            visual_message_return_type: "unseen",
+            limit: String(limit),
+        };
+        if (cursor)
+            params.cursor = cursor;
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/`, params);
+    }
+    async getPendingInbox(cursor, limit = DEFAULT_PAGE_SIZE) {
+        const params = {
+            visual_message_return_type: "unseen",
+            thread_message_limit: "1",
+            persistentBadging: "true",
+            limit: String(limit),
+        };
+        if (cursor)
+            params.cursor = cursor;
+        return this.request("/api/v1/direct_v2/pending_inbox/", params);
+    }
+    async getUserInfo(userId) {
+        return this.request(`/api/v1/users/${userId}/info/`);
+    }
+    // --- WRITE ---
+    async sendMessage(threadId, text) {
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/items/`, undefined, "POST", {
+            item_type: "text",
+            text,
+        });
+    }
+    async sendLink(threadId, linkUrl, text) {
+        const body = {
+            item_type: "link",
+            link_urls: JSON.stringify([linkUrl]),
+        };
+        if (text)
+            body.link_text = text;
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/items/`, undefined, "POST", body);
+    }
+    async reactToMessage(threadId, itemId, emoji = "\u2764\uFE0F") {
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/items/${itemId}/reactions/`, undefined, "POST", {
+            reaction_type: "like",
+            reaction_status: "created",
+            emoji,
+            item_id: itemId,
+            node_type: "item",
+            client_context: String(Date.now()),
+        });
+    }
+    async unsendMessage(threadId, itemId) {
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/items/${itemId}/delete/`, undefined, "POST", {});
+    }
+    async markSeen(threadId, itemId) {
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/items/${itemId}/seen/`, undefined, "POST", {
+            use_unified_inbox: "true",
+            action: "mark_seen",
+        });
+    }
+    async approvePending(threadId) {
+        return this.request(`/api/v1/direct_v2/threads/${threadId}/approve/`, undefined, "POST", {});
+    }
+    async searchUsers(query) {
+        return this.request("/api/v1/direct_v2/ranked_recipients/", {
+            mode: "raven",
+            query,
+            show_threads: "true",
+        });
+    }
+    // --- NEW ---
+    async createThread(recipientIds, text) {
+        return this.request("/api/v1/direct_v2/threads/broadcast/text/", undefined, "POST", {
+            recipient_users: JSON.stringify(recipientIds),
+            action: "send_item",
+            text,
+            client_context: String(Date.now()),
+        });
+    }
+}
+exports.InstagramClient = InstagramClient;

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+export interface InstaUser {
+    pk: string;
+    username: string;
+    full_name: string;
+    profile_pic_url: string;
+    is_verified?: boolean;
+    is_private?: boolean;
+}
+export interface InstaMessageItem {
+    item_id: string;
+    user_id: string;
+    timestamp: number;
+    item_type: string;
+    text?: string;
+    media?: {
+        image_versions2?: {
+            candidates: {
+                url: string;
+            }[];
+        };
+    };
+    link?: {
+        text: string;
+        link_url: string;
+    };
+    reel_share?: {
+        text?: string;
+        media?: {
+            caption?: {
+                text: string;
+            };
+        };
+    };
+    voice_media?: {
+        media: {
+            audio: {
+                audio_src: string;
+            };
+        };
+    };
+    clip?: {
+        clip: {
+            caption?: {
+                text: string;
+            };
+        };
+    };
+    animated_media?: {
+        images?: {
+            fixed_height?: {
+                url: string;
+            };
+        };
+    };
+    media_share?: {
+        caption?: {
+            text: string;
+        };
+        image_versions2?: {
+            candidates: {
+                url: string;
+            }[];
+        };
+    };
+    story_share?: {
+        title?: string;
+        message?: string;
+    };
+    action_log?: {
+        description: string;
+    };
+    reactions?: {
+        emojis?: {
+            emoji: string;
+            sender_id: string;
+        }[];
+    };
+    is_sent_by_viewer?: boolean;
+    reply_to_message?: {
+        text?: string;
+        item_id: string;
+    };
+}
+export interface InstaThread {
+    thread_id: string;
+    thread_title: string;
+    users: InstaUser[];
+    items: InstaMessageItem[];
+    last_activity_at: number;
+    read_state: number;
+    has_older: boolean;
+    oldest_cursor?: string;
+    newest_cursor?: string;
+    is_group: boolean;
+    pending: boolean;
+    archived: boolean;
+    muted: boolean;
+    named: boolean;
+    thread_type?: string;
+    inviter?: InstaUser;
+}
+export interface InstaViewer {
+    pk: string;
+    username: string;
+    full_name: string;
+    profile_pic_url: string;
+    is_verified: boolean;
+}
+export interface InstaInboxResponse {
+    viewer: InstaViewer;
+    inbox: {
+        threads: InstaThread[];
+        has_older: boolean;
+        oldest_cursor?: string;
+    };
+    pending_requests_total: number;
+    seq_id: number;
+}
+export interface InstaThreadResponse {
+    thread: InstaThread;
+}
+export interface InstaUserInfoResponse {
+    user: InstaUser & {
+        biography?: string;
+        follower_count?: number;
+        following_count?: number;
+        media_count?: number;
+        external_url?: string;
+    };
+}
+export interface InstaActionResponse {
+    status: string;
+    payload?: {
+        thread_id?: string;
+        client_context?: string;
+    };
+    thread_id?: string;
+}
+export interface InstaRankedRecipient {
+    user?: InstaUser;
+    thread?: InstaThread;
+}
+export interface InstaSearchUsersResponse {
+    ranked_recipients: InstaRankedRecipient[];
+    expires: number;
+    filtered: boolean;
+    request_id: string;
+    rank_token: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "mcp-instagram-dm",
+  "version": "2.1.0",
+  "description": "MCP server for Instagram Direct Messages — read inbox, send messages, search conversations, and manage DMs through AI assistants",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-instagram-dm": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "instagram",
+    "dm",
+    "direct-messages",
+    "ai",
+    "claude",
+    "chatgpt",
+    "llm",
+    "mcp-server",
+    "automation"
+  ],
+  "author": "Kynux",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kynuxdev/mcp-instagram-dm.git"
+  },
+  "homepage": "https://github.com/Kynuxdev/mcp-instagram-dm#readme",
+  "bugs": {
+    "url": "https://github.com/Kynuxdev/mcp-instagram-dm/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}