mcp-instagram-dm

mcp-instagram-dm

Read, send, and manage Instagram Direct Messages through AI assistants via the Model Context Protocol.

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:

{
  "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)

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 in Chrome and log in
• Press F12 to open DevTools
• Go to Application tab > Cookies > https://www.instagram.com
• 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

Claude Desktop

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

Claude Code

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

Cursor

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

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 for guidelines.

License

MIT