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
pip install 'igsight-mcp[login]' && igsight-mcp login   # recommended session setup
igsight-mcp doctor                     # fast local checklist (+ fixes)
igsight-mcp doctor --online            # optional live Instagram session probe

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 igsight-mcp doctor (local-only by default; doctor --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.

Let your agent set it up

Point your agent at llms.txt and AGENTS.md, then use a one-line prompt:

Install igsight-mcp following llms.txt and run self_test, then give feedback

Example first get_post prompt in your client:

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

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