Skip to main content
Glama

📸 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 Python 3.10+ MCP Protocol Instagrapi AI Vision Open Source

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


🏛️ System Architecture / Sistem Mimarisi

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)"]

Related MCP server: Instagram DM MCP server

📁 Repository Structure

File

Role

server.py

MCP server exposing 16 tools over stdio for DMs, media downloads, comments, posts, stories, reels, and profiles.

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

Long-term per-user JSON memory engine (user_memories/) extracting names, ages, cities, occupations, life facts, and [MEMORY] AI tags.

instagram_client.py

Singleton InstagramClientManager handling session.json, browser sessionid cookie login, 2FA TOTP, proxy routing, and sleep_jitter().

config.py

Environment variable loader via python-dotenv with path resolution for session persistence.

login_test.py

Interactive CLI onboarding script for testing login, 2FA verification, and HTTP 429 browser sessionid recovery.

start.bat / stop.bat

Windows helper scripts to launch and terminate both server.py and auto_responder.py cleanly.

.env.example

Safe environment configuration template (no credentials included).

requirements.txt

Python package dependencies.

LICENSE

Official Apache License 2.0 — free and open for everyone.


🇹🇷 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

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

# Windows (CMD / PowerShell)
copy .env.example .env
# Linux / macOS
cp .env.example .env

.env dosyasını kendi bilgilerinizle doldurun (asla Git'e göndermeyin!):

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)

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

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


🇬🇧 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

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

cp .env.example .env   # On Windows: copy .env.example .env

Edit .env with your credentials (.env and session.json are excluded in .gitignore):

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 createinstructions.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)

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:

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


🇩🇪 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

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:

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

⬆️ Nach oben


🇫🇷 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

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 :

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

⬆️ Haut de page


🇪🇸 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

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:

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

⬆️ Volver arriba


🇷🇺 Русский (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 с опциональной обложкой.

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

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-клиента:

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

⬆️ Наверх


🇸🇦 العربية (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 مع خيار صورة الغلاف.

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

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 على نظام ويندوز أو أضف الإعداد التالي إلى عميل MCP:

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

⬆️ العودة للأعلى


🇮🇷 فارسی (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 همراه با تصویر کاور اختیاری آپلود می‌کند.

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

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 استفاده کنید یا سرور را به تنظیمات کلاینت MCP اضافه نمایید:

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

⬆️ بازگشت به بالا


🇮🇱 עברית (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 עם תמונת שער אופציונלית.

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

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:

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

⬆️ חזרה למעלה


🇨🇳 中文 (简体) (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 短视频(支持自定义封面图)。

🚀 安装与配置

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 客户端配置中加入:

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

⬆️ 返回顶部


🇯🇵 日本語 (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 動画を投稿します。

🚀 セットアップと設定

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 クライアント設定に以下を追加してください:

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

⬆️ ページトップへ戻る


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

This project is licensed under the Apache License, Version 2.0 — see the 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables sending Instagram Direct Messages, including text, photos, and videos, and managing chats, messages, media downloads, users, stories, followers, following, and posts through MCP tool calls.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to retrieve and analyze Instagram posts and profiles, including captions, media, video frames, transcripts, and engagement metrics, through MCP tools.
      43 PyPI
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables sending direct messages, managing chats and media, retrieving user, story, and follower information, and performing engagement actions on Instagram through MCP tools.
      -