Instagram MCP Server

1# Instagram MCP Server
2 
3A professional Model Context Protocol (MCP) server that provides a comprehensive toolkit for interacting with Instagram. This server enables LLMs (like Claude or Gemini) to manage accounts, analyze social graphs, discover content, and engage with the Instagram community directly from their interface.
4 
5## 🚀 Features
6 
7- **Full Account Control**: Edit profile, manage privacy, and track activity.
8- **Advanced Messaging**: Read history, send text/media, and react to messages.
9- **Content Creation**: Support for Photos, Videos, Reels, and Carousel/Albums.
10- **Deep Insights**: Analyze post performance, followers, and engagement.
11- **Social Graph**: Smart comparison tools to find unfollowers and fans.
12- **Discovery**: Search by user, hashtag, or location.
13 
14## 📋 Prerequisites
15 
16- **Node.js**: v18 or higher.
17- **Instagram Account**: Standard account credentials.
18 
19## 🛠 Installation
20 
21```bash
22git clone https://github.com/your-repo/insta-mcp.git
23cd insta-mcp
24npm install
25npm run build
26```
27 
28## ⚙️ Configuration
29 
30The server supports flexible configuration via environment variables or a local JSON file.
31 
32### Environment Variables
33 
34| Variable | Description | Default |
35|----------|-------------|---------|
36| `INSTAGRAM_USERNAME` | Your Instagram username | - |
37| `INSTAGRAM_PASSWORD` | Your Instagram password | - |
38| `INSTA_DATA_DIR` | Path to store sessions/credentials | `./data` |
39 
40### Method 1: `.env` File (Local Dev)
41Create a `.env` in the root:
42```env
43INSTAGRAM_USERNAME=your_user
44INSTAGRAM_PASSWORD=your_pass
45```
46 
47### Method 2: `credentials.json`
48Copy the example and fill in your details:
49```bash
50cp config/credentials.example.json data/credentials.json
51```
52 
53---
54 
55## 🔧 Tools Catalog
56 
57### Account & Activity
58- `get_account_overview`: Get profile stats (followers, following, bio).
59- `get_activity`: See notifications (likes, follows, etc.).
60- `edit_profile`: Update name, bio, website, and email.
61- `block_user`: Block a specific user.
62- `set_privacy`: Toggle between Private and Public account.
63 
64### Social Graph
65- `get_followers`: List a user's followers.
66- `get_following`: List who a user follows.
67- `compare_follow_lists`: Detect "Unfollowers" or "Fans".
68- `follow_user` / `unfollow_user`: Manage friendships.
69 
70### Media & Interaction
71- `get_recent_posts`: View latest posts for any user.
72- `get_post_insights`: Detailed stats (likes, comments, viewers).
73- `upload_photo` / `upload_video` / `upload_reel`: Post content.
74- `upload_album`: Post carousels with multiple items.
75- `search_locations`: Find locations for tagging.
76- `like_post` / `add_comment` / `reply_to_comment`: Engage with posts.
77 
78### Direct Messaging (DM)
79- `get_inbox`: View recent message threads.
80- `get_direct_messages`: Fetch history for a specific thread.
81- `send_direct_message`: Send text to users or groups.
82- `react_to_message`: Add heart reactions to messages.
83- `get_pending_requests`: Manage DM requests.
84- `mute_thread` / `leave_thread`: Thread management.
85 
86### Feeds & Discovery
87- `search_instagram`: Search for users, tags, or places.
88- `get_timeline`: Your main home feed.
89- `get_discover`: The explore page feed.
90- `get_saved_posts`: Your bookmarked collections.
91- `get_liked_posts`: History of your likes.
92- `get_tag_feed`: Recent posts for a hashtag.
93 
94### Stories
95- `get_stories`: View active stories from your tray or a user.
96- `get_highlights`: Access a user's story highlights.
97 
98---
99 
100## 🖥 Usage with MCP Clients
101 
102### Claude Desktop
103Add the following to your `claude_desktop_config.json`:
104 
105```json
106{
107  "mcpServers": {
108    "instagram": {
109      "command": "node",
110      "args": ["/ABSOLUTE/PATH/TO/insta-mcp/dist/index.js"],
111      "env": {
112        "INSTAGRAM_USERNAME": "your_username",
113        "INSTAGRAM_PASSWORD": "your_password"
114      }
115    }
116  }
117}
118```
119 
120### Development
121To run in development mode with auto-reload:
122```bash
123npm run format # Format code
124npm run dev    # Build and start
125```
126 
127## ⚠️ Security & Ethics
128This project uses the `instagram-private-api`. 
129- **Rate Limiting**: The server includes built-in throttling. Avoid aggressive automated requests.
130- **Compliance**: Adhere to Instagram's Terms of Service. Use for personal analytics and legitimate social management only.
131 
132## 📄 License
133MIT