Install Instagram MCP for a personal account

Before you start

You need Python 3.12 or newer, Google Chrome for the login window, FFmpeg and ffprobe, aria2c for the setup downloads, and an MCP-compatible assistant. Windows x86-64 is the platform validated with the real Obscura engine. On other systems, install an appropriate Obscura binary separately and verify compatibility.

For speech, install the optional analysis dependencies and a local multilingual faster-whisper model. The model is about 484 MB; the pinned Windows browser archive is about 69 MB. Downloads are explicit setup steps.

1. Get the source and create an environment

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

Activate the environment in PowerShell with .venv\Scripts\Activate.ps1, or in a Unix shell with source .venv/bin/activate. Then install the package:

python -m pip install ".[analysis]"

Installation is from the source checkout. The project does not currently claim a PyPI release.

2. Install the runtime and model

instagram-mcp-setup --obscura --model
instagram-mcp-doctor

The setup command can install --obscura and --model separately. The automatic browser installation is for Windows x86-64; elsewhere set INSTAGRAM_OBSCURA_BINARY to a compatible installed binary. The model path can be set with INSTAGRAM_WHISPER_MODEL. Choose a multilingual model, not an English-only .en model.

The downloader verifies expected size and SHA-256 for the pinned Obscura and model files. Doctor checks local dependencies without logging in or accessing Instagram; it does not currently check whether Chrome is installed.

3. Add the MCP server to your assistant

Use the absolute path to the environment's executable: .venv/Scripts/instagram-mcp.exe on Windows or .venv/bin/instagram-mcp on Unix. Pass required environment variables through the MCP client's configuration.

codex mcp add instagram -- /absolute/path/to/.venv/bin/instagram-mcp

The example is for Codex. The README has a generic MCP JSON example; configuration formats vary across clients. Restart the client if its tool catalog does not refresh.

4. Sign in and verify the account

1. Ask your assistant to call instagram_health and instagram_login_start.
2. Complete login and any 2FA yourself in the visible Instagram window. Never send passwords or codes in chat.
3. Call instagram_login_finish, then instagram_account_info to verify the session in Obscura.
4. Give the assistant a Reel URL or ask it to inspect saved posts.

After login, Instagram and CDN access goes through Obscura. A login status alone is not proof that the transferred session works; check the account result.

Privacy and troubleshooting

Profiles, cookies, downloaded media and transcripts remain in the local data directory. Protect that directory and keep it out of source control. File uploads are disabled by default; enabling them gives Obscura broader file access. Read the security guide before opting in.

A missing model, unavailable media, a challenge or an incompatible page can stop a specific operation. Follow the reported error; do not treat recognition failure as silence. Instagram support and UI behavior may change.

Continue with the Reel analysis guide or read the full installation reference.