igsight-mcp

MCP server to read and analyze Instagram posts and profiles for AI agents.

Inspired by smorand/mcp-instagram (MIT). See NOTICE for attribution details.

PyPI: igsight-mcp

Quickstart

Fastest path: install into your MCP client, save an Instagram session with igsight-mcp login (or use browser cookies), restart the client, then call get_post on a public Instagram URL.

igsight-mcp install --client cursor    # or: claude | vscode | all
uvx --refresh --from 'igsight-mcp[login]' igsight-mcp login   # recommended session setup
uvx --refresh igsight-mcp doctor                     # fast local checklist (+ fixes)
uvx --refresh igsight-mcp doctor --online            # optional live Instagram session probe

Usage examples

After install, restart your AI client (Claude Desktop, Cursor, or VS Code) and confirm the igsight MCP server is enabled in that client’s MCP settings. Then try natural-language prompts such as:

• “Analyze this post: https://www.instagram.com/p/XXXX/”
• “Summarize the last 10 posts from @profile and tell me what drives engagement”
• “Compare @profile1 and @profile2”
• “Get the comments on this reel and tell me the overall sentiment”
• “Transcribe this reel” (needs igsight-mcp[local] or cloud IGSIGHT_TRANSCRIBE_* keys)

One-click (same config as install; log into Instagram in Chrome first):

Claude Desktop: download igsight-mcp.mcpb from GitHub Releases and open it in Claude Desktop, or run igsight-mcp install --client claude.

Requires uv (for uvx) and Python ≥ 3.11. No API keys required for public posts.

Optional extras

System ffmpeg/ffprobe on PATH is still preferred when available. Without ffprobe, duration is read via ffmpeg.

Run the server manually

uvx igsight-mcp                  # stdio (default)
uvx igsight-mcp --transport http # streamable HTTP on 127.0.0.1:8000

From a git checkout: uvx --from . igsight-mcp

Verify setup

In the client, call check_auth, or from a terminal run uvx --refresh igsight-mcp doctor (local-only by default; add --online for one live cookie probe). Both report cookie source (login, file, browser:…, or none), ffmpeg, transcription backend, and rate limits without echoing secrets. doctor also reads your installed Claude/Cursor/VS Code MCP configs and shows each client's IGSIGHT_COOKIES_FROM_BROWSER.

For AI agents: install yourself

Give any coding agent (Claude Code, Cursor, Codex, Gemini CLI, VS Code Copilot, etc.) this one-line prompt:

Install the igsight MCP for yourself following https://github.com/vinihuge/igsight-mcp/blob/main/llms.txt — detect which client you are running in, run install and login, run doctor, tell me to restart the client, then verify the tools appear.

The agent should follow the step-by-step procedure in llms.txt and AGENTS.md (install → uvx --refresh --from 'igsight-mcp[login]' igsight-mcp login when needed → uvx --refresh igsight-mcp doctor → user restart → self_test).

Example first get_post prompt after setup:

Use the get_post tool on https://www.instagram.com/p/SHORTCODE/ with default settings.

MCP client configuration

Use the same command everywhere:

"command": "uvx",
"args": ["igsight-mcp"]

Add an env block for IGSIGHT_* variables (paths shown are examples—adjust for your machine).

Shared env example

"env": {
  "IGSIGHT_COOKIES_FROM_BROWSER": "chrome",
  "IGSIGHT_CACHE_DIR": "/home/you/.cache/igsight-mcp",
  "IGSIGHT_CACHE_TTL": "3600",
  "IGSIGHT_TRANSCRIBE_BASE_URL": "https://api.groq.com/openai/v1",
  "IGSIGHT_TRANSCRIBE_API_KEY": "your-api-key-here",
  "IGSIGHT_TRANSCRIBE_MODEL": "whisper-large-v3-turbo"
}

Transcription is optional; omit the three IGSIGHT_TRANSCRIBE_* keys to skip speech-to-text.

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "igsight": {
      "command": "uvx",
      "args": ["igsight-mcp"],
      "env": {
        "IGSIGHT_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}

Because the MCP server runs on the same machine as your browser, IGSIGHT_COOKIES_FROM_BROWSER avoids exporting cookies.txt. Alternatively set IGSIGHT_COOKIES_FILE (see docs/cookies.md).

Restart Claude Desktop after saving.

Cursor

Project (repository root): .cursor/mcp.json

Global: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)

{
  "mcpServers": {
    "igsight": {
      "command": "uvx",
      "args": ["igsight-mcp"],
      "env": {
        "IGSIGHT_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}

Reload MCP servers from Cursor settings after editing.

Grok Bot

In Grok Bot MCP settings, add a stdio server with command uvx, arguments ["igsight-mcp"], and the same env keys as above (UI labels vary; the transport is stdio JSON-RPC).

Generic stdio MCP JSON

{
  "mcpServers": {
    "igsight": {
      "command": "uvx",
      "args": ["igsight-mcp"],
      "env": {
        "IGSIGHT_COOKIES_FILE": "/path/to/cookies.txt",
        "IGSIGHT_CACHE_DIR": "/path/to/cache",
        "IGSIGHT_CACHE_TTL": "3600",
        "IGSIGHT_TRANSCRIBE_BASE_URL": "https://api.openai.com/v1",
        "IGSIGHT_TRANSCRIBE_API_KEY": "sk-...",
        "IGSIGHT_TRANSCRIBE_MODEL": "whisper-1"
      }
    }
  }
}

Tools

v1.0 highlights: stories and highlights (cookies), multi-profile compare_profiles, scene-change video frames with uniform fallback, optional OCR extra, nightly upstream smoke in CI, and the full docs/ set linked below.

Environment variables

All configuration uses IGSIGHT_* environment variables (there is no separate config file). Defaults match the implementation in src/igsight_mcp/core/.

There are no IGSIGHT_* rate-limit overrides; limits are fixed in code and reported by check_auth under rate_limit:

Transcription examples

Groq

"IGSIGHT_TRANSCRIBE_BASE_URL": "https://api.groq.com/openai/v1",
"IGSIGHT_TRANSCRIBE_API_KEY": "gsk_...",
"IGSIGHT_TRANSCRIBE_MODEL": "whisper-large-v3-turbo"

OpenAI

"IGSIGHT_TRANSCRIBE_BASE_URL": "https://api.openai.com/v1",
"IGSIGHT_TRANSCRIBE_API_KEY": "sk-...",
"IGSIGHT_TRANSCRIBE_MODEL": "whisper-1"

Alternative OpenAI model example: gpt-4o-mini-transcribe (if your account exposes it on the same API).

All three transcription variables must be set together for the OpenAI-compatible backend; otherwise video/reel posts still return frames but add a transcription warning (unless local faster-whisper is selected).

Local faster-whisper

"IGSIGHT_TRANSCRIBE_BACKEND": "faster_whisper",
"IGSIGHT_WHISPER_MODEL": "small",
"IGSIGHT_WHISPER_DEVICE": "auto"

Install igsight-mcp[local] in the same environment as the server. With IGSIGHT_TRANSCRIBE_BACKEND=auto, the server uses the API when all three IGSIGHT_TRANSCRIBE_* vars are set, otherwise local Whisper when the extra is installed.

Third-party plugins

Install separate Python packages that declare setuptools entry points in group igsight_mcp.plugins. They can add MCP tools without forking the core server. Control loading with IGSIGHT_DISABLE_PLUGINS and IGSIGHT_PLUGINS. See docs/plugins.md and examples/igsight-plugin-hello/.

HTTP transport

For MCP clients that speak streamable HTTP instead of stdio:

export IGSIGHT_HTTP_TOKEN="$(openssl rand -hex 32)"
uvx igsight-mcp --transport http --host 127.0.0.1 --port 8000

HTTP security warning

Streamable HTTP exposes an unauthenticated MCP API on the host and port you bind unless you set IGSIGHT_HTTP_TOKEN. There is no built-in TLS; anyone who can reach the port can call your tools (including Instagram actions using your local cookies).

• Prefer stdio when the MCP client runs on the same machine (uvx igsight-mcp with no flags).
• For HTTP, bind to 127.0.0.1 (the CLI default via --host / IGSIGHT_HOST) and connect only from localhost, or place the service behind a firewall or reverse proxy with authentication.
• Set a long random IGSIGHT_HTTP_TOKEN whenever the listener is not strictly local.
• The Docker image defaults to --host 0.0.0.0 so port publishing works; treat published ports as public unless you add a token, network policy, or proxy auth (see Docker).

Binding to a non-loopback address prints a stderr warning; always set IGSIGHT_HTTP_TOKEN when the port is reachable from other machines.

Cookies

See docs/cookies.md for IGSIGHT_COOKIES_FROM_BROWSER (local browser auto-load), Netscape IGSIGHT_COOKIES_FILE, Keychain/DPAPI troubleshooting, secondary accounts, and keeping cookies out of git.

Account safety and rate limits

igsight-mcp is built for occasional, read-only agent use—not bulk scraping.

• Built-in rate limiting spaces Instagram requests (roughly 3–5 seconds jitter between calls, token bucket, and an hourly budget of 200 requests). Hitting limits raises a rate-limit error; wait and retry.
• No bulk scraping — do not loop thousands of profiles or posts through the tools.
• Avoid datacenter IPs — Instagram often blocks cloud VPS IPs. Prefer a home or office network where you normally use Instagram. check_auth warns when common cloud environment variables are detected.
• Use a secondary account and browser or file cookies rather than hammering anonymous endpoints.

Legal and terms of use

Not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. Instagram is a trademark of Meta.

You are responsible for complying with Instagram’s Terms of Use, applicable copyright law, and privacy rules. This project provides read-only access to public (or session-allowed) content for personal/agent assistance. Do not use it to harass users, bypass paywalls, or redistribute media against creators’ rights. Respect creators and platform policies.

Demo

The looping terminal recording at the top is generated from docs/demo.tape (VHS). Regenerate with vhs docs/demo.tape (optional: gifsicle -O3 --lossy=30 --colors 64 -i docs/assets/demo.gif -o docs/assets/demo.gif) after changing scripts/demo_get_post_fixture.py.

Docker

Published images: ghcr.io/vinihuge/igsight-mcp.

Security: the default command binds streamable HTTP MCP to 0.0.0.0:8000, so anyone who can reach the port can use the server unless you protect it. Strongly recommended: set IGSIGHT_HTTP_TOKEN to a long random secret and configure MCP clients to send Authorization: Bearer <token>. Prefer not publishing the port on untrusted networks; use stdio mode (below) when the client runs on the same host.

The image includes ffmpeg and the igsight-mcp wheel installed with uv. It runs as a non-root user. No local Whisper model is baked in; use API transcription env vars (see above) or install [local] only in custom builds.

Mount volumes for cache and cookies so data survives restarts:

HTTP (default transport)

docker run --rm -p 8000:8000 \
  -e IGSIGHT_HTTP_TOKEN="replace-with-a-long-random-secret" \
  -v igsight-cache:/home/igsight/.cache/igsight-mcp \
  -v "$HOME/.config/igsight/cookies.txt:/home/igsight/cookies.txt:ro" \
  -e IGSIGHT_COOKIES_FILE=/home/igsight/cookies.txt \
  ghcr.io/vinihuge/igsight-mcp:latest

Stdio (Claude Desktop, Cursor, Grok Bot, etc.)

Use -i so the MCP client can use stdin/stdout; override the default HTTP command with --transport stdio:

docker run --rm -i \
  -v igsight-cache:/home/igsight/.cache/igsight-mcp \
  -v "$HOME/.config/igsight/cookies.txt:/home/igsight/cookies.txt:ro" \
  -e IGSIGHT_COOKIES_FILE=/home/igsight/cookies.txt \
  ghcr.io/vinihuge/igsight-mcp:latest \
  --transport stdio

Example MCP client config: command = docker, args = ["run", "--rm", "-i", "-v", "igsight-cache:/home/igsight/.cache/igsight-mcp", "ghcr.io/vinihuge/igsight-mcp:latest", "--transport", "stdio"] (add cookie mounts and env as needed).

Documentation

Detailed guides (architecture, tools, transcription, FAQ, comparisons):

• docs/architecture.md
• docs/tools.md
• docs/transcription.md
• docs/faq.md
• docs/comparison.md
• docs/cookies.md · docs/plugins.md

Agent onboarding: llms.txt and AGENTS.md.

Development

Requires uv. See CONTRIBUTING.md.

uv sync --all-groups
make check          # ruff, mypy --strict, pytest
uv run igsight-mcp  # stdio MCP server
uvx --from . igsight-mcp

Support the project

If igsight-mcp saves you time, consider sponsoring on GitHub Sponsors.

Crypto

Always double-check the network before sending; funds sent on the wrong network may be lost.

Network	Address	QR
Bitcoin (BTC)	bc1qfm4mhns9j4s589lhc9xq6asxpf5x93vhxkdlnn
EVM (Ethereum, BNB Smart Chain, Arbitrum; ETH and USDC/USDT on those networks)	0x816895DFd46328258Bc11E133bD6d659Ccd0E323
Solana (SOL, USDC)	7zvKEwXR5KpbwoorQ4JhjhPSDDkwujKu7tN4BSeAq3Ci
Tron (TRX, USDT TRC-20)	TRk3jC7FjkDpLyHThVogP5pPeeufkSTQ7C

Built by Vinícius · creator of WeTrackWise