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:

   npm install
   

3. Set Up Environment Variables: Create a .env file in the root directory and add your Instagram login credentials:

   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:

npm run dev

2. Production Mode

Compiles the project to JavaScript first, then runs it:

npm run build
npm start

3. Using Docker 🐳

The project includes a Dockerfile ready to build and run the container easily:

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

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