mcp-instagram: Instructions file for Codex

mcp-instagram

Overview

MCP server for downloading Instagram content using yt-dlp. Exposes 4 tools: download_video, download_audio, download_carousel, get_metadata. Supports stdio and HTTP streamable transports.

download_carousel also handles single image posts (GraphImage): yt-dlp raises "There is no video in this post", so image-only content (single or sidecar) is fetched via instaloader metadata + httpx.

Tech Stack: Python 3.13, FastMCP, yt-dlp, Typer, Pydantic, OpenTelemetry

Key Commands

make sync               # Install dependencies
make run ARGS='stdio'   # Run in stdio mode
make run ARGS='http'    # Run in HTTP mode
make run ARGS='skill'   # Print CLI usage guide (for LLMs/agents, stdout only)
make check              # Full quality gate (lint, format, typecheck, security, tests+coverage)
make docker-build       # Build Docker image

Project Structure

• src/mcp_instagram.py : CLI entry point + FastMCP server + tool registrations. The skill command prints SKILL_TEXT (CLI usage guide) to stdout for agents; keep it in sync with the dl command options.
• src/downloader.py : InstagramDownloader service (wraps yt-dlp, async via to_thread)
• src/models.py : Pydantic models: DownloadResult, CarouselResult, MediaMetadata (all carry an optional description = full post caption)
• src/config.py : Settings via pydantic-settings (MCP_INSTAGRAM_ prefix)
• src/logging_config.py : Logging setup with rich + file output
• src/tracing.py : OpenTelemetry tracing with JSONL export

Conventions

• Entry point binary: mcp-instagram
• All yt-dlp calls wrapped in asyncio.to_thread (sync yt-dlp, async interface)
• OTel spans named instagram.<operation> (e.g., instagram.download_video)
• Logs to mcp-instagram.log; traces to mcp-instagram-otel.log
• Cookies: set MCP_INSTAGRAM_COOKIES_FILE to Netscape cookies.txt path
• Settings uses extra="ignore": .env holds unrelated keys (INSTAGRAM_USERNAME/PASSWORD for scripts/list-saved.py) and pydantic-settings would otherwise raise extra_forbidden
• Image extension comes from the HTTP Content-Type, not the URL suffix (CDN serves JPEG on .heic paths)
• Captions: yt-dlp puts the full caption in info["description"]; title is only "Video by <user>" / "Post by <user>". instaloader exposes it as Post.caption. Both go through _caption() (strip, blank becomes None) and land in the description field. Never truncate it in the model; truncate only at display time (_CAPTION_DISPLAY_LIMIT, 500 chars)
• dl --json prints the raw model as JSON on stdout (logs stay on stderr) and forces quiet logging; it is the way for an agent to get the untruncated caption
• Rich printing of user content uses markup=False: a caption containing [...] would otherwise be swallowed as rich markup
• Expected yt-dlp failures (image posts in _get_metadata_sync) are silenced via _QuietYdlLogger
• ffmpeg/ffprobe resolved through _ffbin (absolute path via shutil.which, clear RuntimeError if missing)