Instagram Obscura MCP

A local Instagram MCP server for personal accounts. Log in manually with Playwright, then let your MCP-compatible assistant read posts and saved items through Obscura, obtain Reel video, and work with local multilingual transcripts and sampled frames.

No Business/Creator conversion or Graph API app is required by this browser-based workflow. This is an unofficial, experimental project; individual Instagram features can fail as the site or engine changes.

What you can ask

“Open my saved posts, pick the first Reel, and explain what happens and what is said.”

“Analyze this Japanese Reel and explain it in English. Keep the original transcript.”

“Read the caption and compare it with the images in this carousel.”

Related MCP server: @inssist/mcp

Quick start

Requirements: Python 3.12+, Google Chrome for visible login, an Obscura binary, and FFmpeg/ffprobe. Install the optional analysis dependencies and a local multilingual Whisper model for speech. Windows is the platform with real-engine validation; see limitations.

git clone https://github.com/votsie/instagram-obscura-mcp.git
cd instagram-obscura-mcp
python -m venv .venv

Activate .venv (.venv\Scripts\Activate.ps1 on Windows or source .venv/bin/activate on Unix), then:

python -m pip install ".[analysis]"
instagram-mcp-doctor

Follow installation to install the pinned Obscura release and local multilingual model. Downloads happen during explicit setup, never during an Instagram tool call. The package is installed from source; no PyPI publication is claimed.

Connect your assistant

Use the absolute executable path from your environment; keep it as a separate command argument, even when paths contain spaces.

{
  "mcpServers": {
    "instagram": {
      "command": "/absolute/path/to/.venv/bin/instagram-mcp",
      "args": [],
      "env": {
        "INSTAGRAM_OBSCURA_BINARY": "/absolute/path/to/obscura",
        "INSTAGRAM_WHISPER_MODEL": "/absolute/path/to/whisper-small"
      }
    }
  }
}

On Windows the command is C:/absolute/path/.venv/Scripts/instagram-mcp.exe. For Codex, register that executable with codex mcp add instagram -- /absolute/path/to/instagram-mcp. See client examples and your host's current MCP settings.

First session

1. Ask your assistant to run instagram_health and instagram_login_start.

2. Complete login and 2FA yourself in the visible Instagram window.

3. Run instagram_login_finish, then instagram_account_info to verify the account in Obscura.

4. Give the assistant a Reel URL or ask it to open your saved posts.

Never send passwords or 2FA codes to the assistant. All Instagram/CDN traffic after login stays in Obscura. There is no hidden Chrome or yt-dlp fallback.

Languages, evidence and accuracy

Speech defaults to automatic language detection with a multilingual local model. Omit language unless you know it; original-language text is preserved. Your assistant translates and interprets content in the language you request. English/Russian documentation does not restrict content languages.

Support and accuracy vary by model, language and recording. Code-switching and rare languages can be difficult. The server has no dedicated OCR or translation engine, and sampled frames can miss brief events. See language behavior.

Tools and account actions

22 tools cover login, account information, post reads, saved items, Reel jobs and bounded UI operations. The tool reference lists inputs and expected workflows. A bundled agent skill, AGENTS.md, llms.txt and architecture map make the project easy for coding and tool-using agents to navigate.

Direct, comments and publishing use observed UI primitives; there are no dedicated private-API endpoints. Real sends and publications were not performed as release tests. Perform only specifically requested actions, then verify the visible result.

Uploads are off by default. Explicitly enabling file access also grants Obscura broader file:// reading capability; read the security model before opting in.

Project map

Development

python -m pip install -e ".[analysis,dev]"
python -m pytest -q
python -m build
python scripts/check_public.py

CI does not log into Instagram. Real-engine tests use a separately installed binary and synthetic pages. Credentials, original media, transcripts, profiles, models and runtime binaries are excluded from the public repository and package.

License and acknowledgments

Original code and documentation: MIT. Obscura, Playwright, MCP Python SDK, faster-whisper and FFmpeg make this possible. External software and model licenses are separate; see third-party notices.

Not affiliated with or endorsed by Instagram or Meta.

Website analytics and search visibility

The project website uses free Cloudflare Web Analytics for page views, referrers and performance, with production-host restrictions and DNT/GPC opt-out. It does not track MCP users or Instagram content. Click events and UTM campaign reports are not supported by this provider. Measurement details.

Installation guide · Reel analysis guide · GitHub traffic · Repository activity