mcp-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

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

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://...'
mcp-instagram dl --json 'https://www.instagram.com/reel/<code>/'   # machine-readable, full caption

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.

Captions

Every result carries a description field holding the full post caption, hashtags included. This is usually the richest source of information about a post (titles, names, lists), so read it before analysing the media itself: yt-dlp only sets title to "Video by <user>", never the caption. The human-readable output prints the caption truncated at 500 characters; --json prints the untruncated value. Logs go to stderr, so dl --json ... > result.json yields clean JSON.

HTTP streamable mode

mcp-instagram http
mcp-instagram http --verbose

Default: http://127.0.0.1:8000

Usage instructions for LLMs / agents

mcp-instagram skill

Prints the CLI usage guide (command, options, examples) to stdout. Point an agent at this command instead of embedding the docs in a prompt: on demand, near-zero tokens.

Configuration

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

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

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'