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 MCP server speaks stdio. Most clients launch it for you via config (below). To run manually:

uvx igsight-mcp

From a git checkout:

uvx --from . igsight-mcp

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.

Example first get_post prompt in your client:

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

Related MCP server: Instagram MCP Server

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

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; otherwise video/reel posts still return frames but add a transcription warning.

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

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.

Built by Vinícius · creator of WeTrackWise