instagram-dm-mcp/README.md

Instagram Direct Messages MCP server for Claude Desktop

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

```bash
npm install -g instagram-dm-mcp
```

2. Run the setup script to install Python dependencies:

```bash
instagram-dm-mcp-setup
```

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

```bash
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:
  ```bash
  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:
  ```bash
  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:

```json
"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:

```bash
npx instagram-dm-mcp start
```

### From source

1. Clone this repository:
   ```bash
   git clone <your-repo-url>
   cd insta-mcp
   ```

2. Install dependencies:
   ```bash
   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)

```bash
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:

```bash
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:

```json
{
  "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

```bash
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:

```json
{
  "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):
   ```bash
   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:
   ```bash
   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
```json
{"method": "read_dms", "params": {"limit": 5}}
```
Returns recent DMs with enhanced information including thread details and sender username.

#### Send DM
```json
{"method": "send_dm", "params": {"username": "target_user", "message": "Hi there!"}}
```
Sends a message with automatic retries in case of temporary API failures.

#### Health Check
```json
{"method": "health_check"}
```
Returns detailed information about the server status, login state, version, and system information.

#### Get Greeting (example resource)
```json
{"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

```bash
npx instagram-dm-mcp start
```

You can provide your Instagram credentials in several ways:

1. Command-line arguments:

```bash
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:

```bash
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:

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

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

```bash
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]