Instagram Download MCP Server

# ig-download-mcp English | [繁體中文](README_zh.md) An Instagram MCP (Model Context Protocol) server powered by [Instaloader](https://github.com/instaloader/instaloader), enabling AI assistants (Claude / Claude Code / Codex) to download Instagram content. ## Features - Download posts (images / videos / carousel) - Download videos (Reels / IGTV / video posts) - Download Stories (login required) - Download Highlights (login required) - Download profile pictures - Optionally save metadata (JSON) and captions (text files) - `.env` and environment variable support for credentials ## Requirements - Python >= 3.13 - [uv](https://github.com/astral-sh/uv) ## Quick Start ### 1) Clone ```bash git clone https://github.com/<YOUR_ORG_OR_USER>/ig-download-mcp.git cd ig-download-mcp ``` ### 2) Install dependencies ```bash uv venv uv sync ``` ### 3) Configure credentials (recommended) ```bash cp .env.example .env # Edit .env and fill in your Instagram credentials ``` ### 4) Run the MCP server ```bash uv run ig-download-mcp ``` ## MCP Configuration Replace `/path/to/ig-download-mcp` with your actual installation path. ### Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent file for your platform: ```json { "mcpServers": { "ig-download-mcp": { "command": "uv", "args": ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"] } } } ``` ### Claude Code Edit `~/.claude.json`: ```json { "mcpServers": { "ig-download-mcp": { "command": "uv", "args": ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"] } } } ``` ### Codex (OpenAI) Edit `~/.codex/config.toml`: ```toml [mcp_servers.ig_download_mcp] command = "uv" args = ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"] ``` ## Available Tools | Tool | Description | Login Required | |------|-------------|----------------| | `download_instagram_post` | Download posts (images/videos/carousel) | Optional | | `download_instagram_video` | Download videos only | Optional | | `download_instagram_stories` | Download stories | Required | | `download_instagram_highlights` | Download highlights | Required | | `download_instagram_profile_pic` | Download profile picture | Optional | ## Credentials Recommended: create `.env` in the project root: ```bash cp .env.example .env # Edit .env and fill in your Instagram credentials ``` Or set environment variables: ```bash export IG_USERNAME="your_username" export IG_PASSWORD="your_password" ``` ## Notes / Disclaimer - This project is not affiliated with Instagram or Meta. - You are responsible for complying with Instagram's Terms of Service and all applicable laws. - Stories / Highlights require login. - If 2FA / challenge flows are triggered, Instaloader may fail. - Instaloader includes rate limiting; avoid high-frequency downloads. ## License MIT