dsh-instagram-mcp

DSH Instagram FastMCP Core Service Plugin (@luoyi-dsh/instagram-mcp)

Official foundational Instagram FastMCP service plugin for DeepSeek Harness (DSH).
Manages the Python FastMCP child process lifecycle, centralizes Bot (username) and Master (masterUsername) account bindings, maintains persistent Instagram session credentials and 2FA challenges, and provides standard Model Context Protocol (MCP) tools for DSH AI models and consumer plugins.

[!CAUTION]

⚠️ CRITICAL WARNING & DISCLAIMER

1. Violation of Instagram Terms of Service & Community Guidelines: This plugin and the underlying FastMCP server interact with Instagram via unofficial reverse-engineered APIs (via instagrapi), which expressly violates Instagram / Meta's Terms of Use and Community Guidelines.
2. DO NOT USE YOUR PERSONAL / PRIMARY ACCOUNT: Never use your personal, primary, or business-critical Instagram account! Running automated tasks carries a severe risk of Action Blocks, Challenge Checkpoints, temporary lockouts, and PERMANENT ACCOUNT SUSPENSION / BANNING.
3. Use Dedicated Burner / Alt Accounts & Clean Proxies: Only run this service using disposable test accounts paired with clean residential proxies.
4. Disclaimer: This software is provided solely for educational and research purposes. The developers accept no responsibility or liability for any account bans or restrictions arising from the use of this project.

---

🌟 Key Features

1. Centralized Account Binding:
   • Configure the Bot Instagram account (username) and Master Instagram account (masterUsername) once in MCP; consumer plugins (@luoyi-dsh/instagram-plugin and @luoyi-dsh/instagram-scroll) inherit them automatically.
2. Automated Python Environment & FastMCP Lifecycle:
   • Auto-detects Python / uv, provisions an isolated .venv, and manages the stdio FastMCP subprocess with graceful reconnection.
3. Multi-Stage Fuzzy Post & Reel Search (ig_fuzzy_search_posts):
   • Combines Instagram Top SERP (fbsearch/top_serp), Reels SERP, creator timelines, and hashtag sections to reliably retrieve posts even when hashtag tabs are restricted.
4. Full Post & Reel Context Extraction (ig_get_post_context & ig_get_recent_mentions):
   • Extracts full captions, titles, accessibility visual descriptions, Reel audio metadata, video subtitles, image URLs, and nested comment replies (preview_child_comments).
5. Multi-Layered Anti-Risk Protection:
   • Humanized random jitter, read micro-pacing, hourly write caps, and automatic circuit breaker cooldowns upon detecting rate limits or Action Blocks.

---

📦 Installation

# Via DSH Plugin CLI
dsh plugin --profile web add @luoyi-dsh/instagram-mcp

# Or via npm
npm install @luoyi-dsh/instagram-mcp

---

📖 Operational Guide & Tool Reference

For complete MCP tool definitions, natural language prompts, HTTP REST API routes, cross-plugin SDK examples, and configuration parameters, please refer to AGENTS.md.

---

📁 Directory Structure

dsh-instagram-mcp/
├── cordis.patch.yml               # DSH bundle patch manifest
├── package.json                   # Module definitions and dependencies
├── tsconfig.json                  # TypeScript compiler configuration
├── AGENTS.md                      # Operational & Agent Tool Guide
├── CHANGELOG.md                   # Version release notes
├── README.md                      # English overview (This file)
├── README.zh-Hant.md              # Traditional Chinese overview
├── client.js                      # DSH Web UI control panel
├── vendor/instagram-mcp/          # Standalone Python FastMCP server (server.py, auth.py, core.py)
└── src/                           # TypeScript service, MCP client wrapper, and tool registrations

---

📜 Releases & License

• See CHANGELOG.md for release history.
• Licensed under the MIT License.