Skip to main content
Glama
README.md
<div align="center">

<img src="https://img.icons8.com/fluency/96/instagram-new.png" alt="Instagram MCP Logo" width="88" height="88" />

# 📸 Instagram-MCP & AI Auto-Responder

### *Next-Generation Model Context Protocol (MCP) Server + Multimodal Vision AI DM Assistant with Persistent User Memory*

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge&logo=apache)](./LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Model_Context_Protocol-8A2BE2?style=for-the-badge&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
[![Instagrapi](https://img.shields.io/badge/Powered_by-Instagrapi-E4405F?style=for-the-badge&logo=instagram&logoColor=white)](https://github.com/subzeroid/instagrapi)
[![AI Vision](https://img.shields.io/badge/AI_Vision-LM_Studio_%7C_Gemini_%7C_OpenAI-00C853?style=for-the-badge&logo=openai&logoColor=white)](#)
[![Open Source](https://img.shields.io/badge/Open_for_Everyone-100%25_Free-FF6F00?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](#-license--open-for-everyone)

**16 MCP Tools • Multimodal Vision DM Bot • Persistent JSON Memory • Human-Like Chat Bubbles • Anti-Ban Session & Jitter Engine**

---

### 🌍 Choose Your Language / Dil Seçin / Sprache wählen / Choisir la langue

| | | | |
| :---: | :---: | :---: | :---: |
| [🇹🇷 **Türkçe**](#-türkçe-tr) | [🇬🇧 **English**](#-english-en) | [🇩🇪 **Deutsch**](#-deutsch-de) | [🇫🇷 **Français**](#-français-fr) |
| [🇪🇸 **Español**](#-español-es) | [🇷🇺 **Русский**](#-русский-ru) | [🇸🇦 **العربية**](#-العربية-ar) | [🇮🇷 **فارسی**](#-فارسی-fa) |
| [🇮🇱 **עברית**](#-עברית-he) | [🇨🇳 **中文 (简体)**](#-中文-简体-zh) | [🇯🇵 **日本語**](#-日本語-ja) | [⚖️ **Apache 2.0 License**](./LICENSE) |

</div>

---

## 🏛️ System Architecture / Sistem Mimarisi

```mermaid
flowchart TD
    IDE["AI Clients (Claude Desktop, Cursor, Antigravity IDE)"] -->|stdio MCP| MCP["server.py (16 MCP Tools)"]
    Auto["auto_responder.py (AI DM Listener)"] --> ClientMgr["instagram_client.py (Session & Anti-Ban Jitter)"]
    MCP --> ClientMgr
    ClientMgr -->|"session.json / sessionid / 2FA TOTP / Proxy"| IG["Instagram Private API (instagrapi)"]

    Auto --> Memory["memory_manager.py (user_memories/*.json)"]
    Auto --> Vision["Multimodal AI Cascade"]
    Vision -->|"1. Priority (Local + Vision)"| LMS["LM Studio (localhost:1234/v1)"]
    Vision -->|"2. Fallback (Cloud + Vision)"| Gemini["Google Gemini API (gemini-2.5-flash)"]
    Vision -->|"3. Fallback (Cloud + Vision)"| OpenAI["OpenAI API (gpt-4o-mini)"]
    MCP --> Downloads["downloads/<username>/ (Photo, Video, Audio, View-Once)"]
```

---

## 📁 Repository Structure

| File | Role |
| :--- | :--- |
| [`server.py`](./server.py) | MCP server exposing **16 tools** over `stdio` for DMs, media downloads, comments, posts, stories, reels, and profiles. |
| [`auto_responder.py`](./auto_responder.py) | Autonomous background DM responder with Vision AI cascade, chat-bubble splitting, prompt-leak shield, and human-like typing delays. |
| [`memory_manager.py`](./memory_manager.py) | Long-term per-user JSON memory engine (`user_memories/`) extracting names, ages, cities, occupations, life facts, and `[MEMORY]` AI tags. |
| [`instagram_client.py`](./instagram_client.py) | Singleton `InstagramClientManager` handling `session.json`, browser `sessionid` cookie login, 2FA TOTP, proxy routing, and `sleep_jitter()`. |
| [`config.py`](./config.py) | Environment variable loader via `python-dotenv` with path resolution for session persistence. |
| [`login_test.py`](./login_test.py) | Interactive CLI onboarding script for testing login, 2FA verification, and HTTP `429` browser `sessionid` recovery. |
| [`start.bat`](./start.bat) / [`stop.bat`](./stop.bat) | Windows helper scripts to launch and terminate both `server.py` and `auto_responder.py` cleanly. |
| [`.env.example`](./.env.example) | Safe environment configuration template (no credentials included). |
| [`requirements.txt`](./requirements.txt) | Python package dependencies. |
| [`LICENSE`](./LICENSE) | Official **Apache License 2.0** — free and open for everyone. |

---

<a name="-türkçe-tr"></a>
## 🇹🇷 Türkçe (TR)

> [!TIP]
> **Herkesin Kullanımına Açık:** Bu proje **Apache 2.0 Lisansı** ile tamamen açık kaynaklı olarak paylaşılmıştır. İster kişisel asistan, ister topluluk/işletme yönetimi, ister yapay zeka ajan entegrasyonu için özgürce kullanabilir, değiştirebilir ve dağıtabilirsiniz.

### ✨ Öne Çıkan Özellikler

* **Tam Teşekküllü 16 MCP Aracı (`server.py`):** Claude Desktop, Cursor, Antigravity IDE ve tüm MCP uyumlu yapay zeka istemcilerinin Instagram hesabınızı `stdio` üzerinden güvenle yönetmesini sağlar.
* **Gelişmiş DM Medya Yakalama ve İndirme:** Normal fotoğraf/videoların yanı sıra **tek gösterimlik (view-once / visual_media)** medyaları, **sesli mesajları (voice_media)**, **Reels/XMA** ve **gönderi paylaşımlarını** otomatik ayrıştırır ve `downloads/<kullanici_adi>/` altına çakışma önleyerek (`_1`, `_2`) kaydeder.
* **Çok Modlu (Vision) AI Otomatik Yanıtlayıcı (`auto_responder.py`):**
  * **3 Katmanlı AI Sağlayıcı Önceliği:** Öncelikle yerel **LM Studio** sunucusunu (`http://localhost:1234/v1`) kontrol eder; kapalıysa sırasıyla **Google Gemini (`gemini-2.5-flash`)** veya **OpenAI (`gpt-4o-mini`)** API'lerine geçer.
  * **Görsel Algılama:** Gelen DM fotoğraflarını indirip Base64 formatında Vision modellerine ileterek fotoğrafın içeriğine göre gerçekçi tepki verir.
  * **Doğal Sohbet Baloncukları:** Uzun yanıtları `---`, `[BÖL]`, `[SPLIT]` veya soru işaretlerine göre doğal DM baloncuklarına böler, noktaları ve yapay kalıpları temizler, kullanıcı selam vermediyse gereksiz selam açılışlarını gizler.
  * **Güvenlik Kalkanı:** Prompt veya talimat sızıntısı (`leak_markers`) tespit edilirse mesajın gönderilmesini anında durdurur; `<think>...</think>` düşünme bloklarını temizler.
* **Kalıcı Kullanıcı Hafızası (`memory_manager.py`):** Her kullanıcı için `user_memories/<user_id>.json` dosyası tutar; hem Regex kurallarıyla hem de AI çıktılarındaki `[MEMORY]...[/MEMORY]` etiketleriyle isim, yaş, şehir, meslek ve önemli hayat detaylarını (en fazla son 20 bilgi) saklar, ayrıca son 2 günün sohbet akışını bağlama ekler.
* **Ban Önleme ve Güvenlik Mimarisi (`instagram_client.py`):** `session.json` ile cihaz parmak izini korur, `sleep_jitter()` ile insan benzeri rastgele gecikmeler uygular, `pyotp` ile otomatik 2FA TOTP üretir, HTTP `429` sınırına takılırsa tarayıcı `sessionid` çereziyle girişi destekler ve isteğe bağlı Proxy yapılandırması sunar.

### 🛠️ MCP Araçları Listesi (16 Araç)

| Kategori | Araç Adı | Parametreler | Açıklama |
| :--- | :--- | :--- | :--- |
| 👤 **Profil** | `get_my_profile` | `—` | Giriş yapılan hesabın profil, biyografi ve takipçi bilgilerini getirir. |
| 👤 **Profil** | `get_user_profile` | `username` | Belirtilen Instagram kullanıcısının profil detaylarını getirir. |
| 💬 **DM Okuma** | `get_direct_threads` | `amount=10, unread_only=False` | Gelen kutusundaki sohbetleri (okunmamış filtresiyle) listeler. |
| 💬 **DM Okuma** | `get_thread_messages` | `thread_id, amount=10` | Sohbetteki son mesajları ve medya bilgilerini okur. |
| 📥 **Medya İndirme** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | CDN bağlantısından fotoğraf, video veya ses dosyasını klasörleyip indirir. |
| 📥 **Medya İndirme** | `download_thread_message_media` | `thread_id, message_id` | Tek bir DM mesajındaki medyayı (tek gösterimlik dahil) otomatik indirir. |
| 📥 **Medya İndirme** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | Sohbetteki tüm fotoğraf, video ve sesli mesajları topluca indirir. |
| ✉️ **DM Gönderme** | `send_direct_message` | `recipient_username, message_text` | Kullanıcı adına doğrudan DM gönderir. |
| ✉️ **DM Gönderme** | `reply_to_thread` | `thread_id, message_text` | Mevcut bir sohbete yanıt gönderir. |
| 💭 **Yorumlar** | `get_media_comments` | `media_id, amount=20` | Gönderi veya Reels altındaki yorumları listeler. |
| 💭 **Yorumlar** | `reply_to_comment` | `media_id, comment_id, reply_text` | Belirli bir yoruma yanıt verir. |
| 💭 **Yorumlar** | `like_comment` | `comment_id` | Belirli bir yorumu beğenir. |
| 📸 **İçerik** | `get_my_recent_posts` | `amount=10` | Son paylaşımları ve beğeni/yorum/izlenme istatistiklerini getirir. |
| 📸 **İçerik** | `upload_photo` | `image_path, caption` | Akışta (Feed) fotoğraf paylaşır. |
| 📸 **İçerik** | `upload_story` | `image_path, caption=""` | Hikaye (Story) paylaşır. |
| 🎬 **İçerik** | `upload_reel` | `video_path, caption, thumbnail_path=None` | Kapak görseli opsiyonuyla Reels videosu paylaşır. |

### 🚀 Kurulum ve Kullanım

#### 1. Sanal Ortam ve Bağımlılıklar
```bash
git clone https://github.com/eYushaa/InstaMCP.git
cd InstaMCP
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux / macOS:
source .venv/bin/activate

pip install -r requirements.txt
```

#### 2. Ortam Değişkenlerini (`.env`) Yapılandırın
```bash
# Windows (CMD / PowerShell)
copy .env.example .env
# Linux / macOS
cp .env.example .env
```

`.env` dosyasını kendi bilgilerinizle doldurun (**asla Git'e göndermeyin!**):
```env
INSTAGRAM_USERNAME=kullanici_adiniz
INSTAGRAM_PASSWORD=sifreniz
INSTAGRAM_SESSIONID=
INSTAGRAM_2FA_SEED=
INSTAGRAM_SESSION_PATH=session.json
INSTAGRAM_PROXY=
REQUEST_DELAY_SECONDS=2

# İsteğe Bağlı AI Auto-Responder Anahtarları (LM Studio kapalıysa kullanılır)
GEMINI_API_KEY=
OPENAI_API_KEY=
```

> [!NOTE]
> `auto_responder.py` için dilerseniz proje kökünde `instructions.json` oluşturarak `bot_name`, `system_prompt`, `personality`, `backstory`, `backstory_mode` (`"auto"`, `"always"`, `"off"`), `guidelines`, `forbidden_words`, `response_delay` (`min_seconds`, `max_seconds`) ve `lm_studio` (`api_url`, `model`, `temperature`, `max_tokens`) ayarlarını özelleştirebilirsiniz.

#### 3. İlk Giriş ve Oturum Testi (`session.json` Oluşturma)
```bash
python login_test.py
```
* **2FA (İki Aşamalı Doğrulama):** `.env` içinde `INSTAGRAM_2FA_SEED` yoksa terminal sizden 6 haneli kodu ister.
* **429 Sınırı Çözümü:** Instagram şifreli girişi geçici olarak kısıtlarsa (`429`), tarayıcıdan (`F12 -> Application -> Cookies -> instagram.com`) aldığınız `sessionid` değerini terminale veya `.env` içine yapıştırarak anında oturum oluşturabilirsiniz.

#### 4. Başlatma Seçenekleri
* **Windows Tek Tıkla Başlatma / Durdurma:** `start.bat` hem `server.py` hem `auto_responder.py` servislerini başlatır; `stop.bat` her ikisini durdurur.
* **MCP İstemcisi Yapılandırması (`claude_desktop_config.json` veya `mcp_config.json`):**

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/Scripts/python.exe",
      "args": [
        "/path/to/Instagram-MCP/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```
*(Linux/macOS sistemlerde `command` yolunu `/path/to/Instagram-MCP/.venv/bin/python` olarak ayarlayın.)*

[⬆️ Yukarı Dön](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-english-en"></a>
## 🇬🇧 English (EN)

> [!TIP]
> **Open for Everyone:** Licensed under the **Apache License 2.0**, this project is completely free and open-source for everyone to use, customize, self-host, and redistribute.

### ✨ Key Features

* **16 Comprehensive MCP Tools (`server.py`):** Exposes Instagram automation capabilities over standard `stdio` MCP transport for Claude Desktop, Cursor, Antigravity IDE, and any MCP-compatible AI client.
* **Advanced DM Media & View-Once Extraction:** Parses standard photos/videos, **view-once / disappearing media (`visual_media`)**, **voice notes (`voice_media`)**, **Reels/XMA**, and **shared posts**, saving them neatly into `downloads/<username>/` with automatic collision prevention (`_1`, `_2`).
* **Multimodal Vision AI Auto-Responder (`auto_responder.py`):**
  * **3-Tier AI Provider Cascade:** Prioritizes a local **LM Studio** server (`http://localhost:1234/v1`) and seamlessly falls back to **Google Gemini (`gemini-2.5-flash`)** or **OpenAI (`gpt-4o-mini`)** if local inference is offline.
  * **Vision Perception:** Automatically downloads incoming DM images and encodes them as Base64 data URLs / inline data for context-aware visual replies.
  * **Natural Chat Bubbles:** Splits multi-part AI responses along `---`, `[BÖL]`, `[SPLIT]`, or question boundaries, removes robotic artifacts and `<think>...</think>` blocks, and suppresses redundant greetings if the user didn't greet first.
  * **Prompt-Leak Security Shield:** Halts delivery immediately if internal prompt markers (`leak_markers`) appear in the generated output.
* **Long-Term Per-User Memory (`memory_manager.py`):** Maintains persistent JSON profiles in `user_memories/<user_id>.json`, combining regex fact extraction with AI-emitted `[MEMORY]...[/MEMORY]` tags (capped at the latest 20 key facts) and injecting the last 2 days of conversation history.
* **Anti-Ban & Session Protection (`instagram_client.py`):** Reuses device fingerprints via `session.json`, injects randomized `sleep_jitter()` delays between API calls, supports `pyotp` 2FA TOTP automation, browser `sessionid` cookie login (bypassing `429` login rate limits), and HTTP/SOCKS proxy routing.

### 🛠️ MCP Tools Reference (16 Tools)

| Category | Tool Name | Parameters | Description |
| :--- | :--- | :--- | :--- |
| 👤 **Profile** | `get_my_profile` | `—` | Retrieves your authenticated Instagram account details and follower stats. |
| 👤 **Profile** | `get_user_profile` | `username` | Fetches public/accessible profile metadata for any Instagram username. |
| 💬 **DM Read** | `get_direct_threads` | `amount=10, unread_only=False` | Lists recent inbox threads with optional unread filtering. |
| 💬 **DM Read** | `get_thread_messages` | `thread_id, amount=10` | Reads recent messages and embedded media metadata from a thread. |
| 📥 **Media** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | Downloads a CDN photo, video, or audio file into organized user folders. |
| 📥 **Media** | `download_thread_message_media` | `thread_id, message_id` | Locates and downloads media (including active view-once media) from a message. |
| 📥 **Media** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | Batch-downloads all photos, videos, and voice messages from a thread. |
| ✉️ **DM Send** | `send_direct_message` | `recipient_username, message_text` | Sends a direct message to a target username. |
| ✉️ **DM Send** | `reply_to_thread` | `thread_id, message_text` | Sends a reply directly to an existing conversation thread. |
| 💭 **Comments** | `get_media_comments` | `media_id, amount=20` | Lists comments on a specific post or Reel. |
| 💭 **Comments** | `reply_to_comment` | `media_id, comment_id, reply_text` | Posts a reply to a specific comment. |
| 💭 **Comments** | `like_comment` | `comment_id` | Likes a specific comment by ID. |
| 📸 **Publish** | `get_my_recent_posts` | `amount=10` | Lists your recent posts/Reels with likes, comments, and view counts. |
| 📸 **Publish** | `upload_photo` | `image_path, caption` | Uploads a photo post to your Instagram feed. |
| 📸 **Publish** | `upload_story` | `image_path, caption=""` | Uploads an image to your Instagram Story. |
| 🎬 **Publish** | `upload_reel` | `video_path, caption, thumbnail_path=None` | Uploads a Reels video with an optional custom cover thumbnail. |

### 🚀 Setup & Configuration

#### 1. Create Virtual Environment & Install Dependencies
```bash
git clone https://github.com/eYushaa/InstaMCP.git
cd InstaMCP
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
```

#### 2. Configure `.env`
```bash
cp .env.example .env   # On Windows: copy .env.example .env
```
Edit `.env` with your credentials (`.env` and `session.json` are excluded in `.gitignore`):
```env
INSTAGRAM_USERNAME=your_username
INSTAGRAM_PASSWORD=your_password
INSTAGRAM_SESSIONID=
INSTAGRAM_2FA_SEED=
INSTAGRAM_SESSION_PATH=session.json
INSTAGRAM_PROXY=
REQUEST_DELAY_SECONDS=2

# Optional AI Auto-Responder Fallback Keys
GEMINI_API_KEY=
OPENAI_API_KEY=
```
> [!NOTE]
> Optionally create `instructions.json` in the project root to customize `bot_name`, `system_prompt`, `personality`, `backstory`, `backstory_mode` (`"auto"`, `"always"`, `"off"`), `guidelines`, `forbidden_words`, `response_delay` (`min_seconds`, `max_seconds`), and `lm_studio` (`api_url`, `model`, `temperature`, `max_tokens`).

#### 3. Bootstrap Session (`session.json`)
```bash
python login_test.py
```
If Instagram triggers 2FA or HTTP `429`, follow the interactive prompt to enter your 6-digit TOTP code or paste your browser `sessionid` cookie (`F12 -> Application -> Cookies -> https://www.instagram.com`).

#### 4. Connect to Your MCP Client
Add the server block to `claude_desktop_config.json` or your IDE's `mcp_config.json`:
```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": [
        "/path/to/Instagram-MCP/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```
*(On Windows, use `C:\\path\\to\\Instagram-MCP\\.venv\\Scripts\\python.exe` and double-escaped backslashes. You can also run `start.bat` / `stop.bat` to manage both `server.py` and `auto_responder.py`.)*

[⬆️ Back to Top](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-deutsch-de"></a>
## 🇩🇪 Deutsch (DE)

> [!TIP]
> **Frei für alle nutzbar:** Dieses Projekt steht unter der **Apache-Lizenz 2.0** und kann von jedem kostenlos genutzt, angepasst und weiterverbreitet werden.

### ✨ Hauptfunktionen

* **16 Leistungsstarke MCP-Werkzeuge (`server.py`):** Verbindet Claude Desktop, Cursor, Antigravity IDE und andere MCP-Clients über `stdio` direkt mit Instagram.
* **Umfassende Medien- & Einmalansicht-Extraktion:** Erkennt normale Fotos/Videos, **Einmalansichten (`visual_media` / view-once)**, **Sprachnachrichten (`voice_media`)**, **Reels/XMA** und **geteilte Beiträge** und speichert sie kollisionsfrei (`_1`, `_2`) unter `downloads/<benutzername>/`.
* **Multimodaler Vision-KI Auto-Responder (`auto_responder.py`):**
  * **3-Stufen-KI-Kaskade:** Nutzt bevorzugt lokales **LM Studio** (`http://localhost:1234/v1`) und fällt bei Bedarf automatisch auf **Google Gemini (`gemini-2.5-flash`)** oder **OpenAI (`gpt-4o-mini`)** zurück.
  * **Bilderkennung (Vision):** Eingehende DM-Fotos werden heruntergeladen, Base64-kodiert und direkt vom Vision-Modell ausgewertet.
  * **Natürliche Chat-Blasen & Leak-Schutz:** Teilt lange Antworten natürlich auf (`---`, `[BÖL]`, `[SPLIT]`, Fragezeichen), entfernt `<think>...</think>`-Blöcke und blockiert den Versand bei Prompt-Leaks.
* **Langzeitgedächtnis pro Nutzer (`memory_manager.py`):** Speichert Namen, Alter, Wohnort, Beruf und wichtige Lebensfakten (max. 20 Fakten) in `user_memories/<user_id>.json` über Regex und `[MEMORY]...[/MEMORY]`-Tags inkl. der letzten 2 Tage Chat-Verlauf.
* **Anti-Ban-Schutz (`instagram_client.py`):** Persistente Gerätesitzung (`session.json`), zufällige `sleep_jitter()`-Verzögerungen, automatische 2FA-TOTP-Codes (`pyotp`), Browser-`sessionid`-Login bei `429`-Limits sowie Proxy-Unterstützung.

### 🛠️ Übersicht der 16 MCP-Werkzeuge

| Kategorie | Werkzeugname | Parameter | Beschreibung |
| :--- | :--- | :--- | :--- |
| 👤 **Profil** | `get_my_profile` | `—` | Ruft eigene Kontodaten und Follower-Statistiken ab. |
| 👤 **Profil** | `get_user_profile` | `username` | Lädt Profildaten eines beliebigen Instagram-Nutzers. |
| 💬 **DM Lesen** | `get_direct_threads` | `amount=10, unread_only=False` | Listet aktuelle Posteingangs-Chats (optional nur ungelesene). |
| 💬 **DM Lesen** | `get_thread_messages` | `thread_id, amount=10` | Liest Nachrichten und Medienmetadaten eines Threads. |
| 📥 **Medien** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | Lädt CDN-Medien (Foto/Video/Audio) strukturiert herunter. |
| 📥 **Medien** | `download_thread_message_media` | `thread_id, message_id` | Lädt das Medium einer bestimmten Nachricht (inkl. Einmalansicht) herunter. |
| 📥 **Medien** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | Lädt alle Medien und Sprachnachrichten eines Chats im Stapel herunter. |
| ✉️ **DM Senden** | `send_direct_message` | `recipient_username, message_text` | Sendet eine Direktnachricht an einen Benutzernamen. |
| ✉️ **DM Senden** | `reply_to_thread` | `thread_id, message_text` | Antwortet direkt in einem bestehenden Thread. |
| 💭 **Kommentare** | `get_media_comments` | `media_id, amount=20` | Listet Kommentare unter einem Beitrag oder Reel auf. |
| 💭 **Kommentare** | `reply_to_comment` | `media_id, comment_id, reply_text` | Antwortet auf einen bestimmten Kommentar. |
| 💭 **Kommentare** | `like_comment` | `comment_id` | Liked einen bestimmten Kommentar. |
| 📸 **Beiträge** | `get_my_recent_posts` | `amount=10` | Zeigt aktuelle Beiträge/Reels inkl. Statistiken. |
| 📸 **Beiträge** | `upload_photo` | `image_path, caption` | Veröffentlicht ein Foto im Feed. |
| 📸 **Beiträge** | `upload_story` | `image_path, caption=""` | Veröffentlicht eine Instagram Story. |
| 🎬 **Beiträge** | `upload_reel` | `video_path, caption, thumbnail_path=None` | Lädt ein Reels-Video (optional mit Vorschaubild) hoch. |

### 🚀 Installation & Konfiguration

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

Fügen Sie Ihre `.env`-Zugangsdaten hinzu (`INSTAGRAM_USERNAME`, `INSTAGRAM_PASSWORD`, optional `INSTAGRAM_SESSIONID`, `INSTAGRAM_2FA_SEED`, `INSTAGRAM_PROXY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`) und passen Sie bei Bedarf `instructions.json` an. Starten Sie unter Windows beide Dienste bequem mit `start.bat` (und beenden Sie sie mit `stop.bat`) oder binden Sie `server.py` in Ihre MCP-Konfiguration ein:

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

[⬆️ Nach oben](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-français-fr"></a>
## 🇫🇷 Français (FR)

> [!TIP]
> **Ouvert à tous :** Ce projet est distribué sous licence **Apache 2.0**. Tout le monde peut l'utiliser, le modifier et le partager librement.

### ✨ Fonctionnalités Principales

* **16 Outils MCP Complets (`server.py`) :** Permet à Claude Desktop, Cursor, Antigravity IDE et tout client MCP d'interagir avec Instagram via `stdio`.
* **Capture Avancée des Médias DM :** Extrait les photos/vidéos permanentes, les **médias à vue unique (`visual_media` / view-once)**, les **messages vocaux (`voice_media`)**, les **Reels/XMA** et les publications partagées dans `downloads/<utilisateur>/` sans écrasement de fichiers (`_1`, `_2`).
* **Répondeur Automatique IA Multimodal (`auto_responder.py`) :**
  * **Cascade IA à 3 Niveaux :** Priorise **LM Studio** en local (`http://localhost:1234/v1`), puis bascule vers **Google Gemini (`gemini-2.5-flash`)** ou **OpenAI (`gpt-4o-mini`)**.
  * **Vision par Ordinateur :** Analyse automatiquement les images reçues en DM (encodage Base64) pour formuler des réponses contextuelles.
  * **Bulles de Discussion & Bouclier Anti-Fuite :** Découpe les réponses (`---`, `[BÖL]`, `[SPLIT]`, `?`), supprime `<think>...</think>` et bloque tout envoi si une fuite de prompt est détectée.
* **Mémoire Utilisateur Persistante (`memory_manager.py`) :** Stocke dans `user_memories/<user_id>.json` le prénom, l'âge, la ville, le métier et jusqu'à 20 faits clés via expressions régulières et balises `[MEMORY]...[/MEMORY]`, tout en injectant l'historique des 2 derniers jours.
* **Architecture Anti-Ban (`instagram_client.py`) :** Persistance de session (`session.json`), délais aléatoires `sleep_jitter()`, génération 2FA TOTP (`pyotp`), connexion par cookie `sessionid` (contournement HTTP `429`) et support Proxy.

### 🛠️ Référence des 16 Outils MCP

| Catégorie | Outil | Paramètres | Description |
| :--- | :--- | :--- | :--- |
| 👤 **Profil** | `get_my_profile` | `—` | Récupère les informations et statistiques de votre compte. |
| 👤 **Profil** | `get_user_profile` | `username` | Consulte le profil d'un utilisateur Instagram donné. |
| 💬 **DM Lecture** | `get_direct_threads` | `amount=10, unread_only=False` | Liste les conversations récentes (avec filtre non-lus). |
| 💬 **DM Lecture** | `get_thread_messages` | `thread_id, amount=10` | Lit les messages récents et métadonnées média d'un fil. |
| 📥 **Médias** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | Télécharge un média CDN dans un dossier dédié. |
| 📥 **Médias** | `download_thread_message_media` | `thread_id, message_id` | Télécharge le média d'un message spécifique (y compris vue unique). |
| 📥 **Médias** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | Télécharge en lot toutes les photos, vidéos et notes vocales d'un fil. |
| ✉️ **DM Envoi** | `send_direct_message` | `recipient_username, message_text` | Envoie un message direct à un nom d'utilisateur. |
| ✉️ **DM Envoi** | `reply_to_thread` | `thread_id, message_text` | Répond directement dans une conversation existante. |
| 💭 **Commentaires** | `get_media_comments` | `media_id, amount=20` | Liste les commentaires d'une publication ou d'un Reel. |
| 💭 **Commentaires** | `reply_to_comment` | `media_id, comment_id, reply_text` | Répond à un commentaire précis. |
| 💭 **Commentaires** | `like_comment` | `comment_id` | Aime un commentaire spécifique. |
| 📸 **Publication** | `get_my_recent_posts` | `amount=10` | Récupère vos dernières publications et leurs statistiques. |
| 📸 **Publication** | `upload_photo` | `image_path, caption` | Publie une photo dans le fil d'actualité. |
| 📸 **Publication** | `upload_story` | `image_path, caption=""` | Publie une Story Instagram. |
| 🎬 **Publication** | `upload_reel` | `video_path, caption, thumbnail_path=None` | Publie un Reel avec miniature personnalisable. |

### 🚀 Installation & Configuration

```bash
python -m venv .venv
source .venv/bin/activate   # Windows : .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows : copy .env.example .env
python login_test.py
```

Configurez `.env` (et éventuellement `instructions.json`), utilisez `start.bat` / `stop.bat` sous Windows ou ajoutez le serveur à votre client MCP :

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

[⬆️ Haut de page](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-español-es"></a>
## 🇪🇸 Español (ES)

> [!TIP]
> **Abierto para todos:** Este proyecto está publicado bajo la licencia **Apache 2.0**. Cualquier persona puede usarlo, modificarlo y distribuirlo de forma gratuita.

### ✨ Características Principales

* **16 Herramientas MCP Completas (`server.py`):** Conecta Claude Desktop, Cursor, Antigravity IDE y cualquier cliente MCP a tu cuenta de Instagram mediante transporte `stdio`.
* **Extracción Avanzada de Medios en DM:** Analiza fotos y videos permanentes, **medios efímeros de una sola visualización (`visual_media` / view-once)**, **notas de voz (`voice_media`)**, **Reels/XMA** y publicaciones compartidas, guardándolos en `downloads/<usuario>/` sin sobrescribir archivos (`_1`, `_2`).
* **Auto-Respondedor IA Multimodal con Visión (`auto_responder.py`):**
  * **Cascada de 3 Proveedores IA:** Da prioridad a **LM Studio** local (`http://localhost:1234/v1`) y cambia automáticamente a **Google Gemini (`gemini-2.5-flash`)** o **OpenAI (`gpt-4o-mini`)** si el servidor local no está activo.
  * **Percepción Visual:** Descarga las imágenes recibidas por DM y las envía en Base64 al modelo Vision para generar respuestas naturales basadas en el contenido visual.
  * **Burbujas de Chat Naturales y Escudo Anti-Fugas:** Divide respuestas largas (`---`, `[BÖL]`, `[SPLIT]`, `?`), limpia bloques `<think>...</think>` y detiene el envío si detecta filtración de instrucciones (`leak_markers`).
* **Memoria Persistente por Usuario (`memory_manager.py`):** Almacena archivos JSON por usuario en `user_memories/<user_id>.json` con nombre, edad, ciudad, ocupación y hasta 20 datos clave extraídos mediante expresiones regulares y etiquetas `[MEMORY]...[/MEMORY]`, además del historial reciente de los últimos 2 días.
* **Protección Anti-Baneo (`instagram_client.py`):** Reutiliza la huella del dispositivo en `session.json`, aplica retrasos aleatorios con `sleep_jitter()`, soporta códigos 2FA TOTP (`pyotp`), inicio de sesión con cookie `sessionid` (ideal para evitar límites `429`) y proxies.

### 🛠️ Referencia de las 16 Herramientas MCP

| Categoría | Herramienta | Parámetros | Descripción |
| :--- | :--- | :--- | :--- |
| 👤 **Perfil** | `get_my_profile` | `—` | Obtiene la información y estadísticas de tu cuenta autenticada. |
| 👤 **Perfil** | `get_user_profile` | `username` | Consulta el perfil de cualquier usuario de Instagram. |
| 💬 **DM Lectura** | `get_direct_threads` | `amount=10, unread_only=False` | Lista las conversaciones recientes (con filtro opcional de no leídos). |
| 💬 **DM Lectura** | `get_thread_messages` | `thread_id, amount=10` | Lee los últimos mensajes y metadatos multimedia de un hilo. |
| 📥 **Medios** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | Descarga archivos multimedia desde URL de CDN organizados por usuario. |
| 📥 **Medios** | `download_thread_message_media` | `thread_id, message_id` | Descarga el medio de un mensaje específico (incluyendo view-once). |
| 📥 **Medios** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | Descarga por lotes todas las fotos, videos y audios de un hilo. |
| ✉️ **DM Envío** | `send_direct_message` | `recipient_username, message_text` | Envía un mensaje directo a un nombre de usuario. |
| ✉️ **DM Envío** | `reply_to_thread` | `thread_id, message_text` | Responde directamente en un hilo existente. |
| 💭 **Comentarios** | `get_media_comments` | `media_id, amount=20` | Lista los comentarios de una publicación o Reel. |
| 💭 **Comentarios** | `reply_to_comment` | `media_id, comment_id, reply_text` | Publica una respuesta a un comentario específico. |
| 💭 **Comentarios** | `like_comment` | `comment_id` | Da "Me gusta" a un comentario concreto. |
| 📸 **Publicación** | `get_my_recent_posts` | `amount=10` | Obtiene tus publicaciones recientes y sus métricas. |
| 📸 **Publicación** | `upload_photo` | `image_path, caption` | Publica una foto en el Feed. |
| 📸 **Publicación** | `upload_story` | `image_path, caption=""` | Sube una imagen a tu Historia (Story). |
| 🎬 **Publicación** | `upload_reel` | `video_path, caption, thumbnail_path=None` | Sube un video Reel con miniatura opcional. |

### 🚀 Instalación y Configuración

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

Configura `.env` (y opcionalmente `instructions.json`), usa `start.bat` / `stop.bat` en Windows o añade el servidor a tu cliente MCP:

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

[⬆️ Volver arriba](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-русский-ru"></a>
## 🇷🇺 Русский (RU)

> [!TIP]
> **Открыто для всех:** Проект распространяется под лицензией **Apache 2.0**. Каждый может свободно использовать, изменять и распространять его.

### ✨ Основные возможности

* **16 Полнофункциональных MCP-инструментов (`server.py`):** Обеспечивает подключение Claude Desktop, Cursor, Antigravity IDE и других MCP-клиентов к Instagram по протоколу `stdio`.
* **Продвинутое извлечение медиа из Direct:** Поддерживает обычные фото/видео, **исчезающие медиа однократного просмотра (`visual_media` / view-once)**, **голосовые сообщения (`voice_media`)**, **Reels/XMA** и репосты публикаций, сохраняя файлы в `downloads/<username>/` без перезаписи (`_1`, `_2`).
* **Мультимодальный Vision ИИ Автоответчик (`auto_responder.py`):**
  * **Трёхуровневый каскад ИИ-провайдеров:** В первую очередь использует локальный сервер **LM Studio** (`http://localhost:1234/v1`), а при его недоступности переключается на **Google Gemini (`gemini-2.5-flash`)** или **OpenAI (`gpt-4o-mini`)**.
  * **Распознавание изображений (Vision):** Автоматически скачивает входящие фото из DM и передаёт их в формате Base64 в Vision-модель.
  * **Естественные сообщения и защита от утечки промпта:** Разбивает ответы на короткие сообщения (`---`, `[BÖL]`, `[SPLIT]`, `?`), очищает теги `<think>...</think>` и блокирует отправку при обнаружении системных маркеров (`leak_markers`).
* **Долговременная память пользователей (`memory_manager.py`):** Ведёт JSON-профили в `user_memories/<user_id>.json`, извлекая имя, возраст, город, профессию и до 20 ключевых фактов через регулярные выражения и теги `[MEMORY]...[/MEMORY]`, а также подгружает историю переписки за последние 2 дня.
* **Защита от блокировок (`instagram_client.py`):** Сохраняет отпечаток устройства в `session.json`, добавляет случайные задержки `sleep_jitter()`, поддерживает автоматическую генерацию 2FA TOTP (`pyotp`), вход по cookie `sessionid` (обход ошибки `429`) и прокси.

### 🛠️ Список 16 MCP-инструментов

| Категория | Инструмент | Параметры | Описание |
| :--- | :--- | :--- | :--- |
| 👤 **Профиль** | `get_my_profile` | `—` | Получает данные и статистику вашего аккаунта. |
| 👤 **Профиль** | `get_user_profile` | `username` | Возвращает профиль указанного пользователя Instagram. |
| 💬 **Чтение DM** | `get_direct_threads` | `amount=10, unread_only=False` | Список последних диалогов (с фильтром непрочитанных). |
| 💬 **Чтение DM** | `get_thread_messages` | `thread_id, amount=10` | Читает сообщения и метаданные медиа в выбранном диалоге. |
| 📥 **Медиа** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | Скачивает фото, видео или аудио по CDN-ссылке в папку пользователя. |
| 📥 **Медиа** | `download_thread_message_media` | `thread_id, message_id` | Скачивает медиа конкретного сообщения (включая view-once). |
| 📥 **Медиа** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | Пакетное скачивание всех фото, видео и голосовых сообщений диалога. |
| ✉️ **Отправка DM** | `send_direct_message` | `recipient_username, message_text` | Отправляет личное сообщение по имени пользователя. |
| ✉️ **Отправка DM** | `reply_to_thread` | `thread_id, message_text` | Отправляет ответ в существующий диалог. |
| 💭 **Комментарии** | `get_media_comments` | `media_id, amount=20` | Получает комментарии под публикацией или Reels. |
| 💭 **Комментарии** | `reply_to_comment` | `media_id, comment_id, reply_text` | Отвечает на указанный комментарий. |
| 💭 **Комментарии** | `like_comment` | `comment_id` | Ставит лайк указанному комментарию. |
| 📸 **Публикации** | `get_my_recent_posts` | `amount=10` | Получает последние посты и их статистику. |
| 📸 **Публикации** | `upload_photo` | `image_path, caption` | Публикует фотографию в ленту. |
| 📸 **Публикации** | `upload_story` | `image_path, caption=""` | Публикует историю (Story). |
| 🎬 **Публикации** | `upload_reel` | `video_path, caption, thumbnail_path=None` | Загружает Reels с опциональной обложкой. |

### 🚀 Установка и настройка

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

Заполните `.env` (и при желании `instructions.json`), используйте `start.bat` / `stop.bat` в Windows или добавьте сервер в конфигурацию вашего MCP-клиента:

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

[⬆️ Наверх](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-العربية-ar"></a>
<div dir="rtl" align="right">

## 🇸🇦 العربية (AR)

> [!TIP]
> **متاح للجميع:** هذا المشروع مرخّص بموجب **رخصة Apache 2.0** ومفتوح المصدر بالكامل؛ يمكن للجميع استخدامه وتعديله ومشاركته بحرية تامة.

### ✨ المميزات الرئيسية

* **16 أداة MCP متكاملة (`server.py`):** تتيح لعملاء الذكاء الاصطناعي مثل Claude Desktop وCursor وAntigravity IDE إدارة حساب إنستغرام بأمان عبر بروتوكول `stdio`.
* **استخراج وتحميل وسائط الرسائل الخاصة (DM):** يتعرف تلقائياً على الصور والفيديوهات الدائمة، و**الوسائط ذات المشاهدة الواحدة (`visual_media` / view-once)**، و**الرسائل الصوتية (`voice_media`)**، ومقاطع **Reels/XMA** والمنشورات المشتركة، ويحفظها في `downloads/<username>/` مع منع تضارب الأسماء (`_1`, `_2`).
* **المجيب الآلي الذكي متعدد الوسائط (`auto_responder.py`):**
  * **تسلسل ثلاثي لمزودي الذكاء الاصطناعي:** يعطي الأولوية لخادم **LM Studio** المحلي (`http://localhost:1234/v1`)، وفي حال توقفه ينتقل تلقائياً إلى **Google Gemini (`gemini-2.5-flash`)** أو **OpenAI (`gpt-4o-mini`)**.
  * **الرؤية الحاسوبية (Vision):** يحمّل الصور الواردة في الرسائل الخاصة ويرسلها بصيغة Base64 لتحليلها والرد وفق محتواها بدقة.
  * **فقاعات محادثة طبيعية ودرع حماية:** يقسّم الردود الطويلة (`---`, `[BÖL]`, `[SPLIT]`, `؟`)، يزيل مقاطع التفكير `<think>...</think>`، ويوقف الإرسال فوراً إذا رصد تسريباً للتعليمات البرمجية (`leak_markers`).
* **ذاكرة مستخدم دائمة (`memory_manager.py`):** يحتفظ بملف JSON لكل مستخدم داخل `user_memories/<user_id>.json` لحفظ الاسم والعمر والمدينة والمهنة وما يصل إلى 20 حقيقة مهمة عبر التعبيرات النمطية ووسوم `[MEMORY]...[/MEMORY]` مع تضمين سجل المحادثة لآخر يومين.
* **الحماية من الحظر (`instagram_client.py`):** يحفظ بصمة الجهاز في `session.json`، ويطبق تأخيرات عشوائية عبر `sleep_jitter()`، ويدعم رموز التحقق الثنائي 2FA TOTP عبر `pyotp`، وتسجيل الدخول عبر ملف تعريف الارتباط `sessionid` لتجاوز حد `429`، مع دعم البروكسي.

### 🛠️ قائمة أدوات MCP الـ 16

| الفئة | اسم الأداة | المعاملات | الوصف |
| :--- | :--- | :--- | :--- |
| 👤 **الحساب** | `get_my_profile` | `—` | يجلب بيانات وإحصائيات حسابك المسجّل. |
| 👤 **الحساب** | `get_user_profile` | `username` | يعرض تفاصيل ملف أي مستخدم على إنستغرام. |
| 💬 **قراءة DM** | `get_direct_threads` | `amount=10, unread_only=False` | يعرض أحدث المحادثات مع خيار تصفية غير المقروءة. |
| 💬 **قراءة DM** | `get_thread_messages` | `thread_id, amount=10` | يقرأ أحدث الرسائل وبيانات الوسائط في محادثة محددة. |
| 📥 **الوسائط** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | يحمّل ملف صورة أو فيديو أو صوت من رابط CDN وينظمه في مجلد. |
| 📥 **الوسائط** | `download_thread_message_media` | `thread_id, message_id` | يبحث عن وسائط رسالة معينة ويحمّلها (بما في ذلك العرض لمرة واحدة). |
| 📥 **الوسائط** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | يحمّل جميع الصور والفيديوهات والرسائل الصوتية في محادثة دفعة واحدة. |
| ✉️ **إرسال DM** | `send_direct_message` | `recipient_username, message_text` | يرسل رسالة مباشرة إلى اسم مستخدم محدد. |
| ✉️ **إرسال DM** | `reply_to_thread` | `thread_id, message_text` | يرسل رداً مباشرة داخل محادثة قائمة. |
| 💭 **التعليقات** | `get_media_comments` | `media_id, amount=20` | يعرض التعليقات أسفل منشور أو مقطع Reels. |
| 💭 **التعليقات** | `reply_to_comment` | `media_id, comment_id, reply_text` | يرد على تعليق محدد. |
| 💭 **التعليقات** | `like_comment` | `comment_id` | يسجل إعجاباً بتعليق محدد. |
| 📸 **النشر** | `get_my_recent_posts` | `amount=10` | يجلب أحدث منشوراتك وإحصائيات التفاعل. |
| 📸 **النشر** | `upload_photo` | `image_path, caption` | ينشر صورة جديدة في الخلاصة (Feed). |
| 📸 **النشر** | `upload_story` | `image_path, caption=""` | ينشر قصة (Story) على حسابك. |
| 🎬 **النشر** | `upload_reel` | `video_path, caption, thumbnail_path=None` | ينشر فيديو Reels مع خيار صورة الغلاف. |

### 🚀 التثبيت والإعداد

<div dir="ltr" align="left">

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

</div>

املأ ملف `.env` ببياناتك (ويمكنك تخصيص `instructions.json` اختيارياً)، ثم استخدم `start.bat` و`stop.bat` على نظام ويندوز أو أضف الإعداد التالي إلى عميل MCP:

<div dir="ltr" align="left">

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

</div>

[⬆️ العودة للأعلى](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

</div>

---

<a name="-فارسی-fa"></a>
<div dir="rtl" align="right">

## 🇮🇷 فارسی (FA)

> [!TIP]
> **آزاد برای همه:** این پروژه تحت **مجوز Apache 2.0** منتشر شده و برای استفاده، ویرایش و بازتوزیع توسط همه کاملاً آزاد و متن‌باز است.

### ✨ ویژگی‌های کلیدی

* **۱۶ ابزار کامل MCP (`server.py`):** امکان اتصال ایمن کلاینت‌های هوش مصنوعی مانند Claude Desktop، Cursor و Antigravity IDE به اینستاگرام از طریق پروتکل `stdio`.
* **استخراج و دانلود پیشرفته رسانه در دایرکت:** علاوه بر عکس و ویدیوی عادی، **رسانه‌های یک‌بارمصرف (`visual_media` / view-once)**، **پیام‌های صوتی (`voice_media`)**، **Reels/XMA** و پست‌های اشتراک‌گذاری‌شده را شناسایی و در مسیر `downloads/<username>/` بدون تداخل نام (`_1`, `_2`) ذخیره می‌کند.
* **پاسخ‌گوی خودکار هوشمند چندوجهی (`auto_responder.py`):**
  * **اولویت‌بندی سه‌لایه هوش مصنوعی:** ابتدا سرور محلی **LM Studio** (`http://localhost:1234/v1`) را بررسی می‌کند و در صورت خاموش بودن، به‌صورت خودکار به **Google Gemini (`gemini-2.5-flash`)** یا **OpenAI (`gpt-4o-mini`)** سوئیچ می‌شود.
  * **درک تصویر (Vision):** تصاویر دریافتی در دایرکت را دانلود کرده و در قالب Base64 به مدل بینایی می‌فرستد تا پاسخ مرتبط بدهد.
  * **حباب‌های گفتگوی طبیعی و سپر ضدنشت:** پاسخ‌های طولانی را بر اساس `---`, `[BÖL]`, `[SPLIT]` یا علامت سؤال تقسیم می‌کند، بخش `<think>...</think>` را حذف می‌کند و در صورت تشخیص نشت پرامپت (`leak_markers`) ارسال را متوقف می‌نماید.
* **حافظه بلندمدت کاربر (`memory_manager.py`):** برای هر کاربر فایل `user_memories/<user_id>.json` نگهداری می‌کند؛ نام، سن، شهر، شغل و تا ۲۰ نکته مهم زندگی را با Regex و تگ‌های `[MEMORY]...[/MEMORY]` ذخیره کرده و تاریخچه گفتگوی ۲ روز اخیر را به پرامپت اضافه می‌کند.
* **معماری ضدبن (`instagram_client.py`):** اثر انگشت دستگاه را در `session.json` نگه می‌دارد، با `sleep_jitter()` تأخیر تصادفی انسانی اعمال می‌کند، کدهای 2FA TOTP را با `pyotp` می‌سازد، از ورود با کوکی `sessionid` برای عبور از محدودیت `429` پشتیبانی می‌کند و قابلیت تنظیم پروکسی دارد.

### 🛠️ فهرست ۱۶ ابزار MCP

| دسته | نام ابزار | پارامترها | توضیحات |
| :--- | :--- | :--- | :--- |
| 👤 **پروفایل** | `get_my_profile` | `—` | اطلاعات و آمار حساب کاربری واردشده را دریافت می‌کند. |
| 👤 **پروفایل** | `get_user_profile` | `username` | مشخصات پروفایل هر کاربر اینستاگرام را واکشی می‌کند. |
| 💬 **خواندن DM** | `get_direct_threads` | `amount=10, unread_only=False` | فهرست گفتگوهای اخیر صندوق ورودی (با فیلتر خوانده‌نشده) را نمایش می‌دهد. |
| 💬 **خواندن DM** | `get_thread_messages` | `thread_id, amount=10` | پیام‌های اخیر و متادیتای رسانه‌های یک گفتگو را می‌خواند. |
| 📥 **رسانه** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | فایل عکس، ویدیو یا صوت را از لینک CDN در پوشه کاربر دانلود می‌کند. |
| 📥 **رسانه** | `download_thread_message_media` | `thread_id, message_id` | رسانه یک پیام مشخص (از جمله یک‌بارمشاهده) را دانلود می‌کند. |
| 📥 **رسانه** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | تمام عکس‌ها، ویدیوها و پیام‌های صوتی یک گفتگو را به‌صورت یکجا دانلود می‌کند. |
| ✉️ **ارسال DM** | `send_direct_message` | `recipient_username, message_text` | پیام مستقیم به نام کاربری موردنظر ارسال می‌کند. |
| ✉️ **ارسال DM** | `reply_to_thread` | `thread_id, message_text` | مستقیماً در یک گفتگوی موجود پاسخ ارسال می‌کند. |
| 💭 **نظرات** | `get_media_comments` | `media_id, amount=20` | دیدگاه‌های زیر یک پست یا Reels را فهرست می‌کند. |
| 💭 **نظرات** | `reply_to_comment` | `media_id, comment_id, reply_text` | به یک دیدگاه مشخص پاسخ می‌دهد. |
| 💭 **نظرات** | `like_comment` | `comment_id` | یک دیدگاه مشخص را لایک می‌کند. |
| 📸 **انتشار** | `get_my_recent_posts` | `amount=10` | پست‌های اخیر شما و آمار لایک، کامنت و بازدید را برمی‌گرداند. |
| 📸 **انتشار** | `upload_photo` | `image_path, caption` | یک عکس جدید در فید منتشر می‌کند. |
| 📸 **انتشار** | `upload_story` | `image_path, caption=""` | یک استوری جدید منتشر می‌کند. |
| 🎬 **انتشار** | `upload_reel` | `video_path, caption, thumbnail_path=None` | یک ویدیوی Reels همراه با تصویر کاور اختیاری آپلود می‌کند. |

### 🚀 نصب و راه‌اندازی

<div dir="ltr" align="left">

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

</div>

فایل `.env` (و در صورت نیاز `instructions.json`) را تنظیم کنید، در ویندوز از `start.bat` و `stop.bat` استفاده کنید یا سرور را به تنظیمات کلاینت MCP اضافه نمایید:

<div dir="ltr" align="left">

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

</div>

[⬆️ بازگشت به بالا](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

</div>

---

<a name="-עברית-he"></a>
<div dir="rtl" align="right">

## 🇮🇱 עברית (HE)

> [!TIP]
> **פתוח לשימוש חופשי לכולם:** פרויקט זה מופץ תחת רישיון **Apache 2.0** ופתוח לשימוש, התאמה והפצה חופשית עבור כולם.

### ✨ תכונות עיקריות

* **16 כלי MCP מלאים (`server.py`):** מאפשר ללקוחות בינה מלאכותית כמו Claude Desktop, Cursor ו-Antigravity IDE לנהל את חשבון האינסטגרם בבטחה באמצעות פרוטוקול `stdio`.
* **חילוץ והורדת מדיה מתקדמת מהודעות (DM):** מזהה תמונות וסרטונים רגילים, **מדיה לצפייה חד-פעמית (`visual_media` / view-once)**, **הודעות קוליות (`voice_media`)**, **Reels/XMA** ופוסטים משותפים, ושומר אותם תחת `downloads/<username>/` עם מניעת התנגשות שמות (`_1`, `_2`).
* **משיב אוטומטי חכם מבוסס Vision (`auto_responder.py`):**
  * **מפל ספקי AI תלת-שלבי:** מתעדף שרת מקומי **LM Studio** (`http://localhost:1234/v1`) ועובר אוטומטית ל-**Google Gemini (`gemini-2.5-flash`)** או **OpenAI (`gpt-4o-mini`)** במידה והשרת המקומי כבוי.
  * **ראייה ממוחשבת (Vision):** מוריד תמונות נכנסות ומעביר אותן בקידוד Base64 למודל ה-Vision לתגובה מדויקת ומותאמת לתמונה.
  * **בועות צ'אט טבעיות ומגן דליפת הנחיות:** מפצל תגובות ארוכות לפי `---`, `[BÖL]`, `[SPLIT]` או סימני שאלה, מסיר תגיות `<think>...</think>`, ועוצר שליחה מיידית אם מזוהה דליפת פרומפט (`leak_markers`).
* **זיכרון משתמש ארוך-טווח (`memory_manager.py`):** שומר קבצי JSON לכל משתמש ב-`user_memories/<user_id>.json` הכוללים שם, גיל, עיר, עיסוק ועד 20 עובדות מפתח שחולצו באמצעות Regex ותגיות `[MEMORY]...[/MEMORY]`, יחד עם היסטוריית שיחה של היומיים האחרונים.
* **הגנת Anti-Ban (`instagram_client.py`):** שומר טביעת אצבע של מכשיר ב-`session.json`, מוסיף השהיות אקראיות עם `sleep_jitter()`, מפיק קודי 2FA TOTP אוטומטיים עם `pyotp`, תומך בהתחברות דרך עוגיית `sessionid` (לעקיפת מגבלת `429`) ובתמיכת Proxy.

### 🛠️ רשימת 16 כלי ה-MCP

| קטגוריה | שם הכלי | פרמטרים | תיאור |
| :--- | :--- | :--- | :--- |
| 👤 **פרופיל** | `get_my_profile` | `—` | מחזיר את פרטי החשבון המחובר וסטטיסטיקות עוקבים. |
| 👤 **פרופיל** | `get_user_profile` | `username` | שולף פרטי פרופיל של כל משתמש אינסטגרם. |
| 💬 **קריאת DM** | `get_direct_threads` | `amount=10, unread_only=False` | מציג שיחות אחרונות בתיבת הדואר הנכנס (עם סינון לא נקראו). |
| 💬 **קריאת DM** | `get_thread_messages` | `thread_id, amount=10` | קורא הודעות אחרונות ומטא-דאטה של מדיה בשיחה. |
| 📥 **מדיה** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | מוריד קובץ מדיה מ-CDN לתוך תיקיית משתמש מסודרת. |
| 📥 **מדיה** | `download_thread_message_media` | `thread_id, message_id` | מאתר ומוריד מדיה מהודעה ספציפית (כולל צפייה חד-פעמית). |
| 📥 **מדיה** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | מוריד באצווה את כל התמונות, הסרטונים וההקלטות הקוליות בשיחה. |
| ✉️ **שליחת DM** | `send_direct_message` | `recipient_username, message_text` | שולח הודעה ישירה לשם משתמש מבוקש. |
| ✉️ **שליחת DM** | `reply_to_thread` | `thread_id, message_text` | משיב ישירות בתוך שיחה קיימת. |
| 💭 **תגובות** | `get_media_comments` | `media_id, amount=20` | מציג תגובות מתחת לפוסט או Reel. |
| 💭 **תגובות** | `reply_to_comment` | `media_id, comment_id, reply_text` | מגיב לתגובה ספציפית. |
| 💭 **תגובות** | `like_comment` | `comment_id` | עושה לייק לתגובה מסוימת. |
| 📸 **פרסום** | `get_my_recent_posts` | `amount=10` | מביא את הפוסטים האחרונים שלך ונתוני צפיות/לייקים. |
| 📸 **פרסום** | `upload_photo` | `image_path, caption` | מעלה תמונה חדשה לפיד. |
| 📸 **פרסום** | `upload_story` | `image_path, caption=""` | מעלה תמונה לסטורי (Story). |
| 🎬 **פרסום** | `upload_reel` | `video_path, caption, thumbnail_path=None` | מעלה סרטון Reels עם תמונת שער אופציונלית. |

### 🚀 התקנה והגדרה

<div dir="ltr" align="left">

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

</div>

הגדירו את `.env` (ובאופן אופציונלי `instructions.json`), הפעילו באמצעות `start.bat` / `stop.bat` ב-Windows או הוסיפו את השרת להגדרות לקוח ה-MCP:

<div dir="ltr" align="left">

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

</div>

[⬆️ חזרה למעלה](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

</div>

---

<a name="-中文-简体-zh"></a>
## 🇨🇳 中文 (简体) (ZH)

> [!TIP]
> **面向所有人开放:** 本项目基于 **Apache 2.0 许可证** 开源,任何人都可以免费使用、修改、定制和分发。

### ✨ 核心特性

* **16 个完整 MCP 工具 (`server.py`):** 通过标准 `stdio` 协议将 Claude Desktop、Cursor、Antigravity IDE 等 AI 客户端安全连接至 Instagram 账户。
* **高级私信媒体提取与下载:** 自动解析普通图片/视频、**阅后即焚/单次查看媒体 (`visual_media` / view-once)**、**语音消息 (`voice_media`)**、**Reels/XMA** 及分享的帖子,按 `downloads/<username>/` 分类保存并自动防重名 (`_1`, `_2`)。
* **多模态视觉 AI 自动回复器 (`auto_responder.py`):**
  * **三层 AI 提供商回退机制:** 优先调用本地 **LM Studio** (`http://localhost:1234/v1`),离线时自动切换至 **Google Gemini (`gemini-2.5-flash`)** 或 **OpenAI (`gpt-4o-mini`)**。
  * **视觉理解 (Vision):** 自动下载私信图片并转换为 Base64 发送给视觉模型,结合画面内容自然回复。
  * **自然聊天气泡与防泄露护盾:** 按 `---`、`[BÖL]`、`[SPLIT]` 或问号拆分短消息气泡,清除 `<think>...</think>` 推理标签,检测到提示词泄露标记 (`leak_markers`) 时立即拦截发送。
* **持久化用户记忆引擎 (`memory_manager.py`):** 在 `user_memories/<user_id>.json` 中为每位用户记录姓名、年龄、城市、职业及最多 20 条关键生活事实(结合正则提取与 AI `[MEMORY]...[/MEMORY]` 标签),并注入最近 2 天的对话上下文。
* **防封号与会话保护 (`instagram_client.py`):** 通过 `session.json` 复用设备指纹,调用 `sleep_jitter()` 模拟人工随机延迟,支持 `pyotp` 自动生成 2FA TOTP 验证码、浏览器 `sessionid` Cookie 登录(绕过 `429` 频率限制)及代理配置。

### 🛠️ 16 个 MCP 工具一览

| 分类 | 工具名称 | 参数 | 功能说明 |
| :--- | :--- | :--- | :--- |
| 👤 **个人资料** | `get_my_profile` | `—` | 获取当前登录 Instagram 账号的信息和粉丝统计。 |
| 👤 **个人资料** | `get_user_profile` | `username` | 获取任意 Instagram 用户的公开资料和统计数据。 |
| 💬 **读取私信** | `get_direct_threads` | `amount=10, unread_only=False` | 列出收件箱最近会话(支持仅筛选未读)。 |
| 💬 **读取私信** | `get_thread_messages` | `thread_id, amount=10` | 读取指定会话的最新消息及嵌入式媒体信息。 |
| 📥 **媒体下载** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | 从 CDN 链接下载图片、视频或音频并按用户归档。 |
| 📥 **媒体下载** | `download_thread_message_media` | `thread_id, message_id` | 自动查找并下载某条私信中的媒体(含单次查看)。 |
| 📥 **媒体下载** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | 批量下载会话中的所有图片、视频和语音消息。 |
| ✉️ **发送私信** | `send_direct_message` | `recipient_username, message_text` | 按用户名直接发送私信。 |
| ✉️ **发送私信** | `reply_to_thread` | `thread_id, message_text` | 直接回复现有会话。 |
| 💭 **评论互动** | `get_media_comments` | `media_id, amount=20` | 获取指定帖子或 Reels 的评论列表。 |
| 💭 **评论互动** | `reply_to_comment` | `media_id, comment_id, reply_text` | 回复指定的某条评论。 |
| 💭 **评论互动** | `like_comment` | `comment_id` | 点赞指定评论。 |
| 📸 **内容发布** | `get_my_recent_posts` | `amount=10` | 获取自己最近发布的帖子/Reels 及互动数据。 |
| 📸 **内容发布** | `upload_photo` | `image_path, caption` | 在主页 Feed 发布照片帖子。 |
| 📸 **内容发布** | `upload_story` | `image_path, caption=""` | 发布 Instagram 快拍 (Story)。 |
| 🎬 **内容发布** | `upload_reel` | `video_path, caption, thumbnail_path=None` | 上传 Reels 短视频(支持自定义封面图)。 |

### 🚀 安装与配置

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

填写 `.env`(可选创建 `instructions.json` 自定义人格和提示词),在 Windows 下可使用 `start.bat` / `stop.bat` 一键启停,或在 MCP 客户端配置中加入:

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

[⬆️ 返回顶部](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-日本語-ja"></a>
## 🇯🇵 日本語 (JA)

> [!TIP]
> **誰でも自由に利用可能:** 本プロジェクトは **Apache 2.0 ライセンス** のもとで公開されており、誰でも無償で利用・改変・再配布できます。

### ✨ 主な機能

* **16種類の包括的な MCP ツール (`server.py`):** Claude Desktop、Cursor、Antigravity IDE などの AI クライアントから `stdio` 経由で Instagram を安全に操作できます。
* **高度な DM メディア抽出・保存:** 通常の写真・動画に加え、**1回表示メディア (`visual_media` / view-once)**、**ボイスメッセージ (`voice_media`)**、**Reels/XMA**、シェア投稿を自動解析し、`downloads/<username>/` に重複回避 (`_1`, `_2`) しながら保存します。
* **マルチモーダル Vision AI 自動返信ボット (`auto_responder.py`):**
  * **3段階 AI プロバイダーフォールバック:** ローカルの **LM Studio** (`http://localhost:1234/v1`) を最優先し、未起動時は **Google Gemini (`gemini-2.5-flash`)** または **OpenAI (`gpt-4o-mini`)** へ自動切り替えします。
  * **画像認識 (Vision):** DM で受信した画像をダウンロードし Base64 形式で Vision モデルに渡して自然な返信を生成します。
  * **自然なチャットバブル分割&プロンプト漏洩防止:** `---`、`[BÖL]`、`[SPLIT]` や疑問符でメッセージを自然に分割し、`<think>...</think>` タグを除去、システム指示の漏洩 (`leak_markers`) 検知時は送信を即時ブロックします。
* **長期ユーザーメモリエンジン (`memory_manager.py`):** `user_memories/<user_id>.json` にユーザーごとの名前・年齢・居住都市・職業・ライフイベント(最大20件)を正規表現と `[MEMORY]...[/MEMORY]` タグで保存し、直近2日間の会話履歴をコンテキストに組み込みます。
* **BAN 対策・セッション保護 (`instagram_client.py`):** `session.json` でデバイス情報を維持し、`sleep_jitter()` によるランダム遅延、`pyotp` での 2FA TOTP 自動生成、`429` レート制限を回避するブラウザ `sessionid` Cookie ログイン、Proxy 設定に対応しています。

### 🛠️ MCP ツール一覧(全16個)

| カテゴリ | ツール名 | パラメータ | 説明 |
| :--- | :--- | :--- | :--- |
| 👤 **プロフィール** | `get_my_profile` | `—` | ログイン中のアカウント情報とフォロワー統計を取得します。 |
| 👤 **プロフィール** | `get_user_profile` | `username` | 任意の Instagram ユーザーのプロフィール詳細を取得します。 |
| 💬 **DM 読み取り** | `get_direct_threads` | `amount=10, unread_only=False` | 受信箱の最新スレッド一覧を取得します(未読フィルタ対応)。 |
| 💬 **DM 読み取り** | `get_thread_messages` | `thread_id, amount=10` | 指定スレッドの最新メッセージとメディア情報を読み取ります。 |
| 📥 **メディア保存** | `download_media_file` | `url, username=None, timestamp=None, prefix="photo", filename=None` | CDN URL から写真・動画・音声ファイルをユーザー別フォルダへ保存します。 |
| 📥 **メディア保存** | `download_thread_message_media` | `thread_id, message_id` | 特定メッセージのメディア(1回表示含む)を自動ダウンロードします。 |
| 📥 **メディア保存** | `download_thread_media_batch` | `thread_id, amount=10, unseen_only=False` | スレッド内の全写真・動画・音声メッセージを一括ダウンロードします。 |
| ✉️ **DM 送信** | `send_direct_message` | `recipient_username, message_text` | 指定ユーザー名へダイレクトメッセージを送信します。 |
| ✉️ **DM 送信** | `reply_to_thread` | `thread_id, message_text` | 既存スレッドへ直接返信メッセージを送信します。 |
| 💭 **コメント** | `get_media_comments` | `media_id, amount=20` | 投稿や Reels のコメント一覧を取得します。 |
| 💭 **コメント** | `reply_to_comment` | `media_id, comment_id, reply_text` | 特定のコメントへ返信を投稿します。 |
| 💭 **コメント** | `like_comment` | `comment_id` | 指定したコメントに「いいね」します。 |
| 📸 **投稿管理** | `get_my_recent_posts` | `amount=10` | 最近の投稿・Reels とエンゲージメント統計を取得します。 |
| 📸 **投稿管理** | `upload_photo` | `image_path, caption` | フィードに新しい写真投稿をアップロードします。 |
| 📸 **投稿管理** | `upload_story` | `image_path, caption=""` | Instagram ストーリーに画像を投稿します。 |
| 🎬 **投稿管理** | `upload_reel` | `video_path, caption, thumbnail_path=None` | カバー画像オプション付きで Reels 動画を投稿します。 |

### 🚀 セットアップと設定

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python login_test.py
```

`.env`(必要に応じて `instructions.json` も)を設定し、Windows では `start.bat` / `stop.bat` で起動・停止するか、MCP クライアント設定に以下を追加してください:

```json
{
  "mcpServers": {
    "instagram": {
      "command": "/path/to/Instagram-MCP/.venv/bin/python",
      "args": ["/path/to/Instagram-MCP/server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}
```

[⬆️ ページトップへ戻る](#-choose-your-language--dil-seçin--sprache-wählen--choisir-la-langue)

---

<a name="-license--open-for-everyone"></a>
<div align="center">

## ⚖️ License — Open for Everyone (Apache License 2.0)

This project is licensed under the **Apache License, Version 2.0** — see the [`LICENSE`](./LICENSE) file for full details.
**Everyone is free to use, study, modify, distribute, and build upon this project**, both personally and commercially, in accordance with the Apache 2.0 terms.

> **Security Reminder:** Never commit your `.env`, `session.json`, `cookies.json`, `user_memories/`, or API keys to version control. Always inspect `git status` before pushing.

---

Made with ❤️ for the Open-Source & MCP Community • **Apache-2.0 License**

</div>