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

1. Open Instagram 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

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

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

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