Instagram

Overview

MCP server for downloading Instagram content (videos, reels, audio, single images, carousels) using yt-dlp, with an instaloader + httpx fallback for image-only posts that yt-dlp refuses. 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

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

CLI download

mcp-instagram dl 'https://www.instagram.com/reel/<code>/'      # video (transcoded to H.264 if VP9)
mcp-instagram dl 'https://www.instagram.com/p/<code>/'         # single image or carousel
mcp-instagram dl --audio 'https://www.instagram.com/reel/<code>/'
mcp-instagram dl -o /tmp/out --force 'https://...' 'https://...'

Routing is automatic: get_metadata decides video vs image, image posts go through instaloader + httpx. Image extensions come from the HTTP Content-Type, since Instagram CDN URLs often keep a .heic path while serving JPEG bytes. Existing files are skipped unless --force.

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.

Variable	Default	Description
MCP_INSTAGRAM_OUTPUT_DIR	~/Downloads/instagram	Directory where downloads are saved
MCP_INSTAGRAM_COOKIES_FILE	(empty)	Path to a Netscape-format cookies.txt file
MCP_INSTAGRAM_HTTP_HOST	127.0.0.1	Host for HTTP mode
MCP_INSTAGRAM_HTTP_PORT	8000	Port for HTTP mode
MCP_INSTAGRAM_DEBUG	false	Enable debug mode

Copy .env.example to .env and edit as needed. Unrelated keys in .env (for example INSTAGRAM_USERNAME used by scripts/list-saved.py) are ignored, not rejected.

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

Tool	Description
download_video	Download a video, reel, or IGTV. Returns local path and metadata.
download_audio	Download audio only as MP3. Returns local path and metadata.
download_carousel	Download all items in a carousel/sidecar post, or a single image post. Returns list of paths.
get_metadata	Fetch post metadata without downloading (title, duration, counts, etc.).

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'