# Instagram MCP Server 📸

The **Instagram MCP Server** is a comprehensive Model Context Protocol (MCP) server that allows you to control your Instagram account programmatically and via AI agents. Built with **TypeScript** and the powerful `instagram-private-api` library, it provides a wide range of tools for profile management, interacting with media, sending direct messages, and managing followers.

## 🌟 Features & Available Tools

The server provides the following tools for use via MCP clients:

### 👤 Profile & Search
- `ig_get_profile`: Fetch comprehensive profile data for any user by their username.
- `ig_search_users`: Search for Instagram users using keywords.

### 🖼️ Feeds
- `ig_get_timeline`: Get the recent media feed from your personal timeline.
- `ig_get_user_feed`: Get the media feed grid for a specific user.

### 📸 Media Interaction
- `ig_publish_photo`: Publish a new photo to your feed (Requires the absolute local path to the image and a text caption).
- `ig_like_media`: Like a specific post using its Media ID.
- `ig_comment_media`: Add a text comment to a specific post.

### 💬 Direct Messages
- `ig_get_inbox`: Fetch the latest conversations and messages from your direct inbox.
- `ig_send_message`: Send a direct message to a specific user using their User ID (PK).

### 👥 Relationships
- `ig_follow_user`: Send a follow request to a user.
- `ig_unfollow_user`: Unfollow a user.
- `ig_get_followers`: Extract the list of followers for a specific account.
- `ig_get_following`: Extract the list of accounts that a specific user is following.

---

## ⚙️ Prerequisites

- **Node.js**: Version 18 or newer.
- **npm** or **yarn** for package management.
- An active Instagram account (A dedicated test/bot account is **highly recommended** to avoid getting your primary account banned).

---

## 🚀 Installation & Setup

1. **Access the Project Directory**:
   Make sure you are in the root directory of the project.

2. **Install Dependencies**:
   ```bash
   npm install
   ```

3. **Set Up Environment Variables**:
   Create a `.env` file in the root directory and add your Instagram login credentials:
   ```env
   IG_USERNAME=your_instagram_username
   IG_PASSWORD=your_instagram_password
   ```

---

## 🏃‍♂️ Running the Server

You have multiple options to run the server depending on your environment:

### 1. Development Mode
Uses `ts-node` to run TypeScript files directly without a build step:
```bash
npm run dev
```

### 2. Production Mode
Compiles the project to JavaScript first, then runs it:
```bash
npm run build
npm start
```

### 3. Using Docker 🐳
The project includes a `Dockerfile` ready to build and run the container easily:
```bash
# Build the image
docker build -t instagram-mcp-server .

# Run the container with environment variables
docker run -e IG_USERNAME=your_username -e IG_PASSWORD=your_password -i instagram-mcp-server
```

---

## 🔌 Client Integration (MCP)

### Example: Connecting to Claude Desktop
To link this server with the Claude Desktop app (or any MCP client), edit your client configuration file. (On Windows, Claude's config is usually at `C:\Users\Username\AppData\Roaming\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "instagram": {
      "command": "node",
      "args": [
        "F:\\MCP_Server\\Instagram_MCP_server\\build\\index.js"
      ],
      "env": {
        "IG_USERNAME": "your_username",
        "IG_PASSWORD": "your_password"
      }
    }
  }
}
```
*Make sure to build the project (`npm run build`) before referencing the `build/index.js` path.*

---

## ⚠️ Important Warnings

1. **Bans & Rate Limits**: 
   This project uses `instagram-private-api` which relies on unofficial APIs simulating the mobile app. Excessive use (e.g., rapid consecutive likes, following many accounts in a short time) will almost certainly lead to your account being **restricted or permanently banned** (Action Block / Shadowban).
2. **Use With Caution**: 
   It is strongly recommended to interact gradually and implement time delays between requests if you plan to automate processes.
3. **Two-Factor Authentication (2FA)**: 
   Currently, the server supports simple login. If your account has 2FA enabled, the login process might fail. It's recommended to disable it on your test account or implement programmatic handling for 2FA challenges.

---

## 📝 License
Licensed under the **ISC** License.