Instagram DM MCP Server

An MCP (Model-Consumer Protocol) server for Instagram direct messaging functionality, built with fastmcp and instagrapi. This server enables AI assistants to read and send Instagram direct messages.

Current Version: 1.3.5

Features

• Read recent direct messages from your Instagram inbox with comprehensive thread information
• Send direct messages to Instagram users
• Simple greeting resource (example functionality)
• Health check endpoint with status information
• Proper logging to stderr to avoid JSON parsing issues
• Support for various authentication methods, including environment variables

Installation

As an npm package (recommended)

1. Install the package globally:

npm install -g instagram-dm-mcp

2. Run the setup script to install Python dependencies:

instagram-dm-mcp-setup

3. Register the server with Claude Desktop and configure credentials:

instagram-dm-mcp install

This will automatically register the Instagram DM MCP server with Claude Desktop and add it to your Claude Desktop configuration file. The command will configure the server to use the npx approach, which makes it easier to maintain.

You can provide Instagram credentials in several ways:

• Using command-line arguments:

  instagram-dm-mcp install --session-id YOUR_SESSION_ID --csrf-token YOUR_CSRF_TOKEN --ds-user-id YOUR_DS_USER_ID

• Using a credentials file:

  instagram-dm-mcp install --from-file /path/to/instagram_cookies.json

• Using environment variables (INSTAGRAM_SESSION_ID, INSTAGRAM_CSRF_TOKEN, and INSTAGRAM_DS_USER_ID)

The installer will add these credentials as environment variables in the Claude Desktop configuration file, creating a configuration like this:

"mcpServers": {
  // other servers...
  "InstagramDM": {
    "command": "npx",
    "args": [
      "-y",
      "instagram-dm-mcp",
      "start"
    ],
    "env": {
      "INSTAGRAM_SESSION_ID": "your-session-id",
      "INSTAGRAM_CSRF_TOKEN": "your-csrf-token",
      "INSTAGRAM_DS_USER_ID": "your-ds-user-id"
    }
  }
}

Then start the server:

npx instagram-dm-mcp start

From source

1. Clone this repository:

   git clone <your-repo-url>
   cd insta-mcp

2. Install dependencies:

   pip install -r requirements.txt

Authentication

This server requires authentication with Instagram. You must provide valid Instagram credentials for the server to function correctly. You can provide your Instagram credentials in the following ways (in order of preference):

Option 1: Using Individual Environment Variables (Recommended)

export INSTAGRAM_SESSION_ID="your_session_id"
export INSTAGRAM_CSRF_TOKEN="your_csrf_token"
export INSTAGRAM_DS_USER_ID="your_user_id"

This is the preferred method for use with the FastMCP installation command:

fastmcp install server.py -e INSTAGRAM_SESSION_ID=your_session_id -e INSTAGRAM_CSRF_TOKEN=your_csrf_token -e INSTAGRAM_DS_USER_ID=your_user_id

For Claude Desktop MCP configuration:

{
  "instagramdm": {
    "command": "python",
    "args": [
      "/path/to/server.py"
    ],
    "env": {
      "INSTAGRAM_SESSION_ID": "your_session_id",
      "INSTAGRAM_CSRF_TOKEN": "your_csrf_token",
      "INSTAGRAM_DS_USER_ID": "your_user_id"
    }
  }
}

Option 2: Using a Combined Environment Variable

export INSTAGRAM_COOKIES='{"sessionid": "your_session_id", "csrftoken": "your_csrf_token", "ds_user_id": "your_user_id"}'

Option 3: Using a JSON File

Create a file named instagram_cookies.json in the project directory with your Instagram cookies:

{
  "sessionid": "your_session_id",
  "csrftoken": "your_csrf_token", 
  "ds_user_id": "your_user_id"
}

You can obtain these cookies from your browser's developer tools after logging into Instagram.

Usage

Starting the Server

1. Using FastMCP (recommended):

   fastmcp install server.py -e INSTAGRAM_SESSION_ID=your_session_id -e INSTAGRAM_CSRF_TOKEN=your_csrf_token -e INSTAGRAM_DS_USER_ID=your_user_id

2. Running directly:

   python server.py

   The server will start and be available for MCP clients to connect.

Interacting with the Server

The server provides the following tools that can be used by MCP-compatible clients:

Read DMs

{"method": "read_dms", "params": {"limit": 5}}

Returns recent DMs with enhanced information including thread details and sender username.

Send DM

{"method": "send_dm", "params": {"username": "target_user", "message": "Hi there!"}}

Sends a message with automatic retries in case of temporary API failures.

Health Check

{"method": "health_check"}

Returns detailed information about the server status, login state, version, and system information.

Get Greeting (example resource)

{"method": "get_greeting", "params": {"name": "Alice"}}

Simple example of a resource-style endpoint.

Response Format

All responses follow the standard MCP format. For tools like read_dms and send_dm, you'll receive a structured response with a status field indicating success or failure.

Security Notes

• This implementation uses cookies for authentication which should be kept secure.
• Environment variables are the recommended way to provide credentials for better security.
• Keep your session IDs and tokens confidential - they provide full access to your Instagram account.
• For production use, consider implementing a more secure authentication mechanism.
• Using unofficial APIs like instagrapi may violate Instagram's terms of service. Use responsibly.
• This server is intended for personal use with your own Instagram account, not for automation of multiple accounts.

Troubleshooting

• If you see JSON parsing errors in the logs, this usually indicates that some unexpected output is being sent to stdout. The latest version redirects all output to stderr to prevent this issue.
• If authentication fails, check that your Instagram session is still valid. Instagram sessions can expire, requiring you to update your credentials.

Changelog

Version 1.3.3

• Added interactive credential prompts in CLI install command
• Improved handling of missing credentials
• Fixed environment variable handling in Claude config file

Version 1.3.2

• Updated configuration to use the correct mcpServers key in Claude Desktop config

Version 1.3.1

• Fixed Claude Desktop configuration structure
• Improved documentation for environment variables
• Updated to use npx command format for easier maintenance

Version 1.3.0

• Added new install command to register server with Claude Desktop
• Enhanced error handling and logging
• Improved authentication options with multiple credential sources
• Updated documentation

Version 1.2.8

• Fixed health check function
• Improved logging to use stderr for better JSON compatibility
• Updated setup script to install dependencies globally
• The server includes automatic retry mechanisms for temporary API failures, but persistent failures may indicate API changes or rate limiting.
• Use the health_check tool to verify your server status and confirm that you're properly authenticated.

Using the npm package

Starting the server

npx instagram-dm-mcp start

You can provide your Instagram credentials in several ways:

1. Command-line arguments:

npx instagram-dm-mcp start --session-id "YOUR_SESSION_ID" --csrf-token "YOUR_CSRF_TOKEN" --ds-user-id "YOUR_DS_USER_ID"

2. Environment variables:

export INSTAGRAM_SESSION_ID="YOUR_SESSION_ID"
export INSTAGRAM_CSRF_TOKEN="YOUR_CSRF_TOKEN"
export INSTAGRAM_DS_USER_ID="YOUR_DS_USER_ID"
npx instagram-dm-mcp start

3. From a JSON file:

npx instagram-dm-mcp start --from-file instagram_cookies.json

4. Interactive prompt (if no credentials provided)

Claude Desktop MCP Configuration

To use this MCP server with Claude Desktop, add the following to your Claude Desktop MCP configuration file (typically located at ~/.config/Claude/mcp_config.json):

"instagramdm": {
  "command": "npx",
  "args": [
    "-y",
    "instagram-dm-mcp",
    "start"
  ],
  "env": {
    "INSTAGRAM_SESSION_ID": "YOUR_SESSION_ID_HERE",
    "INSTAGRAM_CSRF_TOKEN": "YOUR_CSRF_TOKEN_HERE",
    "INSTAGRAM_DS_USER_ID": "YOUR_DS_USER_ID_HERE"
  }
}

Publishing to npm

If you want to publish your own version to npm:

npm login
npm publish

Changelog

Version 1.2.1

• Added npm package support
• Fixed stability issues
• Simplified code for improved reliability

Version 1.2.0

• Added retry mechanisms for improved reliability
• Enhanced DM response format with more thread information
• Fixed JSON parsing issues by redirecting all output to stderr
• Added comprehensive health check with detailed status information
• Improved error logging and handling

Version 1.2.1

• Added support for environment variables for authentication
• Implemented proper logging system
• Created example MCP configuration for Claude Desktop

Version 1.0.0

• Initial release with basic read/send DM functionality

License

[Specify your license here]