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

Prerequisites

Install ffmpeg from your OS package manager (for example brew install ffmpeg, apt install ffmpeg, or ffmpeg.org).

Run the server

The default MCP transport is stdio (what Claude Desktop, Cursor, and Grok Bot expect). You can also run streamable HTTP for remote clients or Docker (see HTTP transport and Docker).

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

Local Whisper (no API key): install the optional extra, then set IGSIGHT_TRANSCRIBE_BACKEND=faster_whisper (or auto when API vars are unset):

uv pip install 'igsight-mcp[local]'   # or: uv sync --extra local

Verify setup

After configuring your MCP client, call check_auth (no arguments). It reports cookie file status, ffmpeg, transcription config, cache paths, and built-in rate limits—without returning secret values (API keys and cookie contents are never echoed).

Fix any items in warnings (for example missing cookies file, loose file permissions, or datacenter IP hints) before calling get_post.

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_FILE": "/home/you/.config/igsight/cookies.txt",
  "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_FILE": "/home/you/.config/igsight/cookies.txt"
      }
    }
  }
}

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_FILE": "/home/you/.config/igsight/cookies.txt"
      }
    }
  }
}

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

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

Cookies

See docs/cookies.md for exporting Netscape cookies.txt, chmod 600, 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 exported 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