instamcp 2.1.1__tar.gz

instamcp-2.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mpython77
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

instamcp-2.1.1/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: instamcp
+Version: 2.1.1
+Summary: Production-grade MCP server for Instagram — 79 tools: scraping, DMs, scheduling, uploads, social actions, sentiment analysis, multi-account pool
+Author-email: mpython77 <notnightmarelabs1@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mpython77/instagram-mcp
+Project-URL: Repository, https://github.com/mpython77/instagram-mcp
+Project-URL: Issues, https://github.com/mpython77/instagram-mcp/issues
+Keywords: instagram,mcp,model-context-protocol,claude,scraping,social-media,instagram-api,anthropic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: curl-cffi>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: uvloop>=0.20; sys_platform != "win32"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Dynamic: license-file
+
+# instagram-mcp
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue) ![MCP](https://img.shields.io/badge/MCP-compatible-green) ![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey) [![CI](https://github.com/mpython77/instagram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mpython77/instagram-mcp/actions/workflows/ci.yml) [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/mpython77/instagram-mcp/pkgs/container/instagram-mcp)
+
+Production-grade MCP server for Instagram. **79 tools** — 30 anonymous (no credentials), 48 authenticated, 1 auto-mode. Built on `curl_cffi` with Chrome TLS impersonation, adaptive rate limiting, smart caching, multi-account pool, and challenge/2FA resolver.
+
+Works with **Claude Desktop**, **Claude Code**, and any MCP-compatible AI client.
+
+---
+
+## Auth Tiers
+
+| Tier | Symbol | Requirement | Tools |
+|------|--------|-------------|-------|
+| Anonymous | 🌐 | None | 28 |
+| Authenticated | 🔐 | `cookies.json` with valid Instagram session | 48 |
+| Auto-mode | 🌐/🔐 | Anon by default, upgrades when cookies present | 1 |
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/mpython77/instagram-mcp.git
+cd instagram-mcp
+pip install -e .
+instagram-mcp
+```
+
+With `uv`:
+
+```bash
+uv sync && uv run --quiet instagram-mcp
+```
+
+### Cookie Setup
+
+1. Log in to Instagram in your browser.
+2. Install [Cookie-Editor](https://cookie-editor.com/) and navigate to `instagram.com`.
+3. Export cookies as **JSON**.
+4. Save as `cookies.json` in the project root, or set `INSTAGRAM_MCP_COOKIES=/path/to/file`.
+
+> Use a dedicated account — not your personal account. Sessions expire; refresh `cookies.json` if you get 401 errors.
+
+---
+
+## MCP Config
+
+### Claude Desktop
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "instagram": {
+      "command": "instagram-mcp",
+      "env": {
+        "INSTAGRAM_MCP_COOKIES": "/absolute/path/to/cookies.json"
+      }
+    }
+  }
+}
+```
+
+With `uv`:
+
+```json
+{
+  "mcpServers": {
+    "instagram": {
+      "command": "uv",
+      "args": ["run", "--project", "/path/to/instagram-mcp", "instagram-mcp"],
+      "env": {
+        "INSTAGRAM_MCP_COOKIES": "/absolute/path/to/cookies.json"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add instagram instagram-mcp --env INSTAGRAM_MCP_COOKIES=/path/to/cookies.json
+```
+
+---
+
+## Docker
+
+```bash
+docker run -d \
+  -e INSTAGRAM_MCP_COOKIES=/data/cookies.json \
+  -v /path/to/cookies.json:/data/cookies.json:ro \
+  -p 8000:8000 \
+  ghcr.io/mpython77/instagram-mcp:latest
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INSTAGRAM_MCP_COOKIES` | `""` | Path to `cookies.json` or `cookies.txt` |
+| `INSTAGRAM_MCP_PROXIES` | `""` | Comma-separated proxy URLs (or use `proxies.txt`, one per line) |
+| `INSTAGRAM_MCP_IMPERSONATE` | `chrome142` | curl_cffi impersonation profile |
+| `INSTAGRAM_MCP_TIMEOUT` | `10` | Per-request timeout in seconds |
+| `INSTAGRAM_MCP_EXPORT_DIR` | `./exports` | Auto-export directory for JSON results |
+| `INSTAGRAM_MCP_TOOLSETS` | `all` | Comma-separated toolsets to enable: `profile`, `analysis`, `content`, `social_graph`, `batch`, `server` |
+| `INSTAGRAM_MCP_HIDE_AUTH_WHEN_NO_COOKIES` | `""` | Set `1` to hide auth-only tools when no cookies are loaded |
+| `INSTAGRAM_MCP_CACHE_DISABLED` | `""` | Set `1` to disable all caching |
+
+---
+
+## Tools
+
+### 🌐 Profile & Feed
+
+| Tool | Description |
+|------|-------------|
+| `instagram_profile` | Profile metadata, feed tags (up to 12 posts), activity status |
+| `instagram_feed_deep` | Paginated feed — up to 200 posts with date filtering |
+| `instagram_bulk_check` | Check up to 20 accounts in parallel with activity status |
+| `instagram_compare_profiles` | Side-by-side comparison of 2–5 accounts |
+
+### 🌐 Analysis
+
+| Tool | Description |
+|------|-------------|
+| `instagram_analyze_engagement` | ER%, content mix, best posting days, top hashtags across up to 200 posts |
+| `instagram_find_collab_network` | Map usertags, @mentions, co-authors, and paid sponsors across posts |
+| `instagram_account_report` | Full profile + engagement + collab network in one call |
+| `instagram_caption_analyze` | Caption patterns: avg length, hashtag density, emoji/CTA rates |
+| `instagram_compare_followers` | Compare follower/following sets — find unfollowers or non-mutuals |
+| `instagram_analyze_comments` | Sentiment analysis on comments — pos/neu/neg, emoji stats, keywords (EN/UZ/RU) |
+
+### 🌐 Content
+
+| Tool | Description |
+|------|-------------|
+| `instagram_post` | Full post details: location (GPS + Maps), music, usertags, coauthors |
+| `instagram_post_bulk` | Fetch up to 50 posts in parallel by shortcode or URL |
+| `instagram_post_comments` | Fetch comments with likes and thread structure (up to 500) |
+
+### 🌐/🔐 Hashtag & Discovery
+
+| Tool | Description |
+|------|-------------|
+| `instagram_hashtag` | Top posts for a hashtag — anon: 12 posts; auth: up to 300. Auto-upgrades. |
+| `instagram_hashtag_deep` | Top accounts, content breakdown, best posting hour across up to 500 posts |
+| `instagram_niche_top` | Account leaderboard for a hashtag ranked by engagement/post count/total likes |
+| `instagram_hashtag_suggest` | Related hashtag suggestions by analyzing top posts under a seed tag |
+
+### 🌐 Threads
+
+| Tool | Description |
+|------|-------------|
+| `instagram_threads_profile` | Profile metadata from Threads (threads.net) |
+| `instagram_threads_posts` | Recent posts for a Threads user |
+
+### 🔐 Authenticated Feed & Activity
+
+| Tool | Description |
+|------|-------------|
+| `instagram_home_feed` | Your authenticated home feed |
+| `instagram_saved_posts` | Your bookmarked posts |
+| `instagram_liked_posts` | Posts you have liked |
+| `instagram_activity_feed` | Your recent activity notifications |
+| `instagram_post_likers` | Users who liked a specific post (up to ~98) |
+
+### 🔐 Discovery
+
+| Tool | Description |
+|------|-------------|
+| `instagram_similar_accounts` | Accounts Instagram considers similar (internal chaining API) |
+| `instagram_search` | Search users + hashtags by keyword |
+| `instagram_user_search` | User search with higher-quality ranking (authenticated API) |
+| `instagram_user_id_lookup` | Look up a user's numeric ID by username |
+
+### 🔐 Social Graph
+
+| Tool | Description |
+|------|-------------|
+| `instagram_followers_list` | Recent followers with mutual follow status |
+| `instagram_following_list` | Full following list with close-friends detection |
+| `instagram_user_followers` | Paginated followers for any user by numeric user_id |
+| `instagram_user_following` | Paginated following for any user by numeric user_id |
+| `instagram_tagged_by` | Posts by other accounts that tag this account |
+| `instagram_reposts` | Content this account actively reposted |
+
+### 🔐 Media
+
+| Tool | Description |
+|------|-------------|
+| `instagram_reels` | Account's reels with play counts (only tool that exposes `play_count`) |
+| `instagram_stories` | Currently active stories (cached 2 min) |
+| `instagram_highlights` | Highlights tray + optional story items inside |
+| `instagram_audio_reels` | Reels using a specific audio track by `audio_cluster_id` |
+| `instagram_location_posts` | Top posts at a location by Instagram location ID or name |
+| `instagram_media_insights` | Impressions, reach, saves for your own posts (Business/Creator only) |
+
+### 🔐 Interactions
+
+| Tool | Description |
+|------|-------------|
+| `instagram_post_like` | Like or unlike a post |
+| `instagram_post_save` | Save or unsave (bookmark) a post |
+| `instagram_post_comment` | Post a comment |
+| `instagram_comment_reply` | Reply to a comment |
+| `instagram_comment_like` | Like or unlike a comment |
+| `instagram_comment_hide` | Hide a comment on your own post |
+| `instagram_delete_comment` | Delete a comment |
+| `instagram_toggle_comments` | Disable or enable comments on your post |
+| `instagram_post_delete` | Delete one of your own posts |
+| `instagram_follow_user` | Follow or unfollow a user |
+| `instagram_block_user` | Block or unblock a user |
+| `instagram_account_privacy` | Switch account between public and private |
+| `instagram_edit_profile` | Edit bio, display name, website, email, or phone |
+| `instagram_publish_story` | Publish a photo as a Story (24h) |
+| `instagram_story_mark_seen` | Mark stories as viewed |
+| `instagram_story_reply` | Reply to a story via DM |
+
+### 🔐 DM
+
+| Tool | Description |
+|------|-------------|
+| `instagram_dm_inbox` | Read DM inbox (threads list) |
+| `instagram_dm_thread` | Fetch messages in a specific thread |
+| `instagram_dm_send` | Send a text message |
+| `instagram_dm_send_photo` | Send a photo |
+| `instagram_dm_send_video` | Send a video |
+| `instagram_dm_media_messages` | Fetch media messages in a thread |
+| `instagram_dm_react` | Add or remove an emoji reaction on a message |
+| `instagram_dm_unsend` | Delete a sent message |
+| `instagram_dm_mute` | Mute or unmute a thread |
+| `instagram_dm_share_post` | Share a post to a DM thread |
+| `instagram_dm_mark_seen` | Mark a thread as seen |
+
+### 🔐 Upload & Download
+
+| Tool | Description |
+|------|-------------|
+| `instagram_upload_photo` | Upload 1–10 images as a post or carousel |
+| `instagram_upload_reel` | Upload an MP4 as a Reel |
+| `instagram_upload_video` | Upload an MP4 as a regular video post |
+| `instagram_download` | Download all media from a post (single/video/carousel) to local disk |
+
+### 🔐 Broadcast & Automation
+
+| Tool | Description |
+|------|-------------|
+| `instagram_broadcast_channel` | Read a creator's Broadcast Channel (info or messages) |
+| `instagram_schedule` | Schedule posts for future publishing (`add`/`list`/`cancel`/`status`) |
+| `instagram_monitor` | Poll accounts for new posts; fire webhooks on new post |
+| `instagram_sessions` | Manage multiple accounts via `INSTAGRAM_MCP_COOKIES_<ALIAS>` env vars |
+| `instagram_oauth` | Full Graph API OAuth 2.0 flow (`init_flow`/`exchange_code`/`refresh_token`/`status`) |
+
+### 🌐 Batch & Server
+
+| Tool | Description |
+|------|-------------|
+| `instagram_batch_scrape` | Scrape up to 2000 profiles; `profile_only=True` gives 30–60× speedup |
+| `instagram_server` | Diagnostics and cache management (`status`/`clear_cache`/`clear_user`/`reload_cookies`) |
+| `instagram_submit_verification_code` | Submit SMS/Email/2FA code to resolve a pending checkpoint and restore the session |
+
+---
+
+## Limitations
+
+- **Private accounts:** Feed, posts, stories, and highlights are not accessible without following the account.
+- **Follower pagination:** Restricted to ~50 for other accounts; unlimited only for your own account.
+- **Play counts:** Only `instagram_reels` exposes `play_count` — the standard feed API omits it.
+- **Session expiry:** Cookies expire. Use `instagram_server action=reload_cookies` to refresh without restarting.
+- **Write operations:** Like, comment, follow, upload, DM actions — rate limits apply. Avoid rapid consecutive writes.
+- **Anonymous hashtag blocks:** Some hashtags (#swimwear, #fitness, etc.) block anonymous HTML scraping.
+- **Account restrictions:** Comment, reply, and follow may return "something went wrong" on new or restricted accounts — this is Instagram-side, not a bug.
+
+---
+
+## FAQ
+
+**Do I need to log in?**  
+No. 28 tools work anonymously with no credentials. 48 tools require `cookies.json`. `instagram_hashtag` auto-switches based on whether cookies are present.
+
+**Why `curl_cffi` instead of `requests`?**  
+Instagram blocks `requests` and `aiohttp` at the TLS handshake level by JA3/JA4 fingerprint. `curl_cffi` impersonates Chrome's TLS stack, bypassing this check.
+
+**How do I get play counts for reels?**  
+Use `instagram_reels`. The standard feed API (`instagram_feed_deep`) does not include `play_count`.
+
+**What happens on rate limiting?**  
+The adaptive rate limiter detects 429s, backs off (×0.7 RPS), rotates proxy, and retries. After 5 consecutive 429s the circuit breaker opens for 60s.
+
+**How do I use multiple Instagram accounts?**  
+Set `INSTAGRAM_MCP_COOKIES_<ALIAS>` env vars (e.g., `INSTAGRAM_MCP_COOKIES_BRAND=cookies_brand.json`). Use `instagram_sessions action=list` to see available sessions.
+
+**Are `exports/` files safe to commit?**  
+No — they may contain PII. Add `exports/` to `.gitignore`.
+
+**How do I refresh cookies without restarting?**  
+`instagram_server action=reload_cookies`

instamcp-2.1.1/README.md

@@ -0,0 +1,304 @@
+# instagram-mcp
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue) ![MCP](https://img.shields.io/badge/MCP-compatible-green) ![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey) [![CI](https://github.com/mpython77/instagram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mpython77/instagram-mcp/actions/workflows/ci.yml) [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/mpython77/instagram-mcp/pkgs/container/instagram-mcp)
+
+Production-grade MCP server for Instagram. **79 tools** — 30 anonymous (no credentials), 48 authenticated, 1 auto-mode. Built on `curl_cffi` with Chrome TLS impersonation, adaptive rate limiting, smart caching, multi-account pool, and challenge/2FA resolver.
+
+Works with **Claude Desktop**, **Claude Code**, and any MCP-compatible AI client.
+
+---
+
+## Auth Tiers
+
+| Tier | Symbol | Requirement | Tools |
+|------|--------|-------------|-------|
+| Anonymous | 🌐 | None | 28 |
+| Authenticated | 🔐 | `cookies.json` with valid Instagram session | 48 |
+| Auto-mode | 🌐/🔐 | Anon by default, upgrades when cookies present | 1 |
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/mpython77/instagram-mcp.git
+cd instagram-mcp
+pip install -e .
+instagram-mcp
+```
+
+With `uv`:
+
+```bash
+uv sync && uv run --quiet instagram-mcp
+```
+
+### Cookie Setup
+
+1. Log in to Instagram in your browser.
+2. Install [Cookie-Editor](https://cookie-editor.com/) and navigate to `instagram.com`.
+3. Export cookies as **JSON**.
+4. Save as `cookies.json` in the project root, or set `INSTAGRAM_MCP_COOKIES=/path/to/file`.
+
+> Use a dedicated account — not your personal account. Sessions expire; refresh `cookies.json` if you get 401 errors.
+
+---
+
+## MCP Config
+
+### Claude Desktop
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "instagram": {
+      "command": "instagram-mcp",
+      "env": {
+        "INSTAGRAM_MCP_COOKIES": "/absolute/path/to/cookies.json"
+      }
+    }
+  }
+}
+```
+
+With `uv`:
+
+```json
+{
+  "mcpServers": {
+    "instagram": {
+      "command": "uv",
+      "args": ["run", "--project", "/path/to/instagram-mcp", "instagram-mcp"],
+      "env": {
+        "INSTAGRAM_MCP_COOKIES": "/absolute/path/to/cookies.json"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add instagram instagram-mcp --env INSTAGRAM_MCP_COOKIES=/path/to/cookies.json
+```
+
+---
+
+## Docker
+
+```bash
+docker run -d \
+  -e INSTAGRAM_MCP_COOKIES=/data/cookies.json \
+  -v /path/to/cookies.json:/data/cookies.json:ro \
+  -p 8000:8000 \
+  ghcr.io/mpython77/instagram-mcp:latest
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INSTAGRAM_MCP_COOKIES` | `""` | Path to `cookies.json` or `cookies.txt` |
+| `INSTAGRAM_MCP_PROXIES` | `""` | Comma-separated proxy URLs (or use `proxies.txt`, one per line) |
+| `INSTAGRAM_MCP_IMPERSONATE` | `chrome142` | curl_cffi impersonation profile |
+| `INSTAGRAM_MCP_TIMEOUT` | `10` | Per-request timeout in seconds |
+| `INSTAGRAM_MCP_EXPORT_DIR` | `./exports` | Auto-export directory for JSON results |
+| `INSTAGRAM_MCP_TOOLSETS` | `all` | Comma-separated toolsets to enable: `profile`, `analysis`, `content`, `social_graph`, `batch`, `server` |
+| `INSTAGRAM_MCP_HIDE_AUTH_WHEN_NO_COOKIES` | `""` | Set `1` to hide auth-only tools when no cookies are loaded |
+| `INSTAGRAM_MCP_CACHE_DISABLED` | `""` | Set `1` to disable all caching |
+
+---
+
+## Tools
+
+### 🌐 Profile & Feed
+
+| Tool | Description |
+|------|-------------|
+| `instagram_profile` | Profile metadata, feed tags (up to 12 posts), activity status |
+| `instagram_feed_deep` | Paginated feed — up to 200 posts with date filtering |
+| `instagram_bulk_check` | Check up to 20 accounts in parallel with activity status |
+| `instagram_compare_profiles` | Side-by-side comparison of 2–5 accounts |
+
+### 🌐 Analysis
+
+| Tool | Description |
+|------|-------------|
+| `instagram_analyze_engagement` | ER%, content mix, best posting days, top hashtags across up to 200 posts |
+| `instagram_find_collab_network` | Map usertags, @mentions, co-authors, and paid sponsors across posts |
+| `instagram_account_report` | Full profile + engagement + collab network in one call |
+| `instagram_caption_analyze` | Caption patterns: avg length, hashtag density, emoji/CTA rates |
+| `instagram_compare_followers` | Compare follower/following sets — find unfollowers or non-mutuals |
+| `instagram_analyze_comments` | Sentiment analysis on comments — pos/neu/neg, emoji stats, keywords (EN/UZ/RU) |
+
+### 🌐 Content
+
+| Tool | Description |
+|------|-------------|
+| `instagram_post` | Full post details: location (GPS + Maps), music, usertags, coauthors |
+| `instagram_post_bulk` | Fetch up to 50 posts in parallel by shortcode or URL |
+| `instagram_post_comments` | Fetch comments with likes and thread structure (up to 500) |
+
+### 🌐/🔐 Hashtag & Discovery
+
+| Tool | Description |
+|------|-------------|
+| `instagram_hashtag` | Top posts for a hashtag — anon: 12 posts; auth: up to 300. Auto-upgrades. |
+| `instagram_hashtag_deep` | Top accounts, content breakdown, best posting hour across up to 500 posts |
+| `instagram_niche_top` | Account leaderboard for a hashtag ranked by engagement/post count/total likes |
+| `instagram_hashtag_suggest` | Related hashtag suggestions by analyzing top posts under a seed tag |
+
+### 🌐 Threads
+
+| Tool | Description |
+|------|-------------|
+| `instagram_threads_profile` | Profile metadata from Threads (threads.net) |
+| `instagram_threads_posts` | Recent posts for a Threads user |
+
+### 🔐 Authenticated Feed & Activity
+
+| Tool | Description |
+|------|-------------|
+| `instagram_home_feed` | Your authenticated home feed |
+| `instagram_saved_posts` | Your bookmarked posts |
+| `instagram_liked_posts` | Posts you have liked |
+| `instagram_activity_feed` | Your recent activity notifications |
+| `instagram_post_likers` | Users who liked a specific post (up to ~98) |
+
+### 🔐 Discovery
+
+| Tool | Description |
+|------|-------------|
+| `instagram_similar_accounts` | Accounts Instagram considers similar (internal chaining API) |
+| `instagram_search` | Search users + hashtags by keyword |
+| `instagram_user_search` | User search with higher-quality ranking (authenticated API) |
+| `instagram_user_id_lookup` | Look up a user's numeric ID by username |
+
+### 🔐 Social Graph
+
+| Tool | Description |
+|------|-------------|
+| `instagram_followers_list` | Recent followers with mutual follow status |
+| `instagram_following_list` | Full following list with close-friends detection |
+| `instagram_user_followers` | Paginated followers for any user by numeric user_id |
+| `instagram_user_following` | Paginated following for any user by numeric user_id |
+| `instagram_tagged_by` | Posts by other accounts that tag this account |
+| `instagram_reposts` | Content this account actively reposted |
+
+### 🔐 Media
+
+| Tool | Description |
+|------|-------------|
+| `instagram_reels` | Account's reels with play counts (only tool that exposes `play_count`) |
+| `instagram_stories` | Currently active stories (cached 2 min) |
+| `instagram_highlights` | Highlights tray + optional story items inside |
+| `instagram_audio_reels` | Reels using a specific audio track by `audio_cluster_id` |
+| `instagram_location_posts` | Top posts at a location by Instagram location ID or name |
+| `instagram_media_insights` | Impressions, reach, saves for your own posts (Business/Creator only) |
+
+### 🔐 Interactions
+
+| Tool | Description |
+|------|-------------|
+| `instagram_post_like` | Like or unlike a post |
+| `instagram_post_save` | Save or unsave (bookmark) a post |
+| `instagram_post_comment` | Post a comment |
+| `instagram_comment_reply` | Reply to a comment |
+| `instagram_comment_like` | Like or unlike a comment |
+| `instagram_comment_hide` | Hide a comment on your own post |
+| `instagram_delete_comment` | Delete a comment |
+| `instagram_toggle_comments` | Disable or enable comments on your post |
+| `instagram_post_delete` | Delete one of your own posts |
+| `instagram_follow_user` | Follow or unfollow a user |
+| `instagram_block_user` | Block or unblock a user |
+| `instagram_account_privacy` | Switch account between public and private |
+| `instagram_edit_profile` | Edit bio, display name, website, email, or phone |
+| `instagram_publish_story` | Publish a photo as a Story (24h) |
+| `instagram_story_mark_seen` | Mark stories as viewed |
+| `instagram_story_reply` | Reply to a story via DM |
+
+### 🔐 DM
+
+| Tool | Description |
+|------|-------------|
+| `instagram_dm_inbox` | Read DM inbox (threads list) |
+| `instagram_dm_thread` | Fetch messages in a specific thread |
+| `instagram_dm_send` | Send a text message |
+| `instagram_dm_send_photo` | Send a photo |
+| `instagram_dm_send_video` | Send a video |
+| `instagram_dm_media_messages` | Fetch media messages in a thread |
+| `instagram_dm_react` | Add or remove an emoji reaction on a message |
+| `instagram_dm_unsend` | Delete a sent message |
+| `instagram_dm_mute` | Mute or unmute a thread |
+| `instagram_dm_share_post` | Share a post to a DM thread |
+| `instagram_dm_mark_seen` | Mark a thread as seen |
+
+### 🔐 Upload & Download
+
+| Tool | Description |
+|------|-------------|
+| `instagram_upload_photo` | Upload 1–10 images as a post or carousel |
+| `instagram_upload_reel` | Upload an MP4 as a Reel |
+| `instagram_upload_video` | Upload an MP4 as a regular video post |
+| `instagram_download` | Download all media from a post (single/video/carousel) to local disk |
+
+### 🔐 Broadcast & Automation
+
+| Tool | Description |
+|------|-------------|
+| `instagram_broadcast_channel` | Read a creator's Broadcast Channel (info or messages) |
+| `instagram_schedule` | Schedule posts for future publishing (`add`/`list`/`cancel`/`status`) |
+| `instagram_monitor` | Poll accounts for new posts; fire webhooks on new post |
+| `instagram_sessions` | Manage multiple accounts via `INSTAGRAM_MCP_COOKIES_<ALIAS>` env vars |
+| `instagram_oauth` | Full Graph API OAuth 2.0 flow (`init_flow`/`exchange_code`/`refresh_token`/`status`) |
+
+### 🌐 Batch & Server
+
+| Tool | Description |
+|------|-------------|
+| `instagram_batch_scrape` | Scrape up to 2000 profiles; `profile_only=True` gives 30–60× speedup |
+| `instagram_server` | Diagnostics and cache management (`status`/`clear_cache`/`clear_user`/`reload_cookies`) |
+| `instagram_submit_verification_code` | Submit SMS/Email/2FA code to resolve a pending checkpoint and restore the session |
+
+---
+
+## Limitations
+
+- **Private accounts:** Feed, posts, stories, and highlights are not accessible without following the account.
+- **Follower pagination:** Restricted to ~50 for other accounts; unlimited only for your own account.
+- **Play counts:** Only `instagram_reels` exposes `play_count` — the standard feed API omits it.
+- **Session expiry:** Cookies expire. Use `instagram_server action=reload_cookies` to refresh without restarting.
+- **Write operations:** Like, comment, follow, upload, DM actions — rate limits apply. Avoid rapid consecutive writes.
+- **Anonymous hashtag blocks:** Some hashtags (#swimwear, #fitness, etc.) block anonymous HTML scraping.
+- **Account restrictions:** Comment, reply, and follow may return "something went wrong" on new or restricted accounts — this is Instagram-side, not a bug.
+
+---
+
+## FAQ
+
+**Do I need to log in?**  
+No. 28 tools work anonymously with no credentials. 48 tools require `cookies.json`. `instagram_hashtag` auto-switches based on whether cookies are present.
+
+**Why `curl_cffi` instead of `requests`?**  
+Instagram blocks `requests` and `aiohttp` at the TLS handshake level by JA3/JA4 fingerprint. `curl_cffi` impersonates Chrome's TLS stack, bypassing this check.
+
+**How do I get play counts for reels?**  
+Use `instagram_reels`. The standard feed API (`instagram_feed_deep`) does not include `play_count`.
+
+**What happens on rate limiting?**  
+The adaptive rate limiter detects 429s, backs off (×0.7 RPS), rotates proxy, and retries. After 5 consecutive 429s the circuit breaker opens for 60s.
+
+**How do I use multiple Instagram accounts?**  
+Set `INSTAGRAM_MCP_COOKIES_<ALIAS>` env vars (e.g., `INSTAGRAM_MCP_COOKIES_BRAND=cookies_brand.json`). Use `instagram_sessions action=list` to see available sessions.
+
+**Are `exports/` files safe to commit?**  
+No — they may contain PII. Add `exports/` to `.gitignore`.
+
+**How do I refresh cookies without restarting?**  
+`instagram_server action=reload_cookies`