mcp-instagram

Overview

MCP server for downloading Instagram content (videos, reels, audio, carousels) using yt-dlp. Supports both stdio and HTTP streamable transports, selectable via a CLI argument.

Tech Stack: Python 3.13, FastMCP 2.x, yt-dlp, Typer, Pydantic, OpenTelemetry, Ruff, mypy

Related MCP server: MCP YouTube Downloader

Installation

uv tool install .

After installation, the mcp-instagram binary is available system-wide.

Usage

stdio mode (for Claude Desktop, pi)

mcp-instagram stdio
mcp-instagram stdio --verbose
mcp-instagram stdio --quiet

HTTP streamable mode

mcp-instagram http
mcp-instagram http --verbose

Default: http://127.0.0.1:8000

Configuration

All settings are loaded from environment variables (prefix MCP_INSTAGRAM_) or a .env file.

Copy .env.example to .env and edit as needed.

Claude Desktop / pi MCP config (stdio)

Add to your claude_desktop_config.json or pi MCP config:

{
  "mcpServers": {
    "mcp-instagram": {
      "command": "mcp-instagram",
      "args": ["stdio"]
    }
  }
}

Cookies setup

Instagram limits access to public content and blocks most authenticated content without cookies. To provide cookies, log into Instagram in your browser, export your cookies as a Netscape-format cookies.txt file (e.g., using the "Get cookies.txt LOCALLY" Chrome extension), save it anywhere on disk, then set MCP_INSTAGRAM_COOKIES_FILE=/path/to/cookies.txt in your .env or environment. The file is passed directly to yt-dlp's cookiefile option.

Tools

Development

make sync        # Install dependencies
make check       # Full quality gate (lint, format, typecheck, security, tests)
make test        # Run tests only
make run ARGS='stdio --help'