ig-download-mcp

English | 繁體中文

An Instagram MCP (Model Context Protocol) server powered by 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

Quick Start

1) Clone

git clone https://github.com/<YOUR_ORG_OR_USER>/ig-download-mcp.git
cd ig-download-mcp

2) Install dependencies

uv venv
uv sync

3) Configure credentials (recommended)

cp .env.example .env
# Edit .env and fill in your Instagram credentials

4) Run the MCP server

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:

{
  "mcpServers": {
    "ig-download-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"]
    }
  }
}

Claude Code

Edit ~/.claude.json:

{
  "mcpServers": {
    "ig-download-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"]
    }
  }
}

Codex (OpenAI)

Edit ~/.codex/config.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:

cp .env.example .env
# Edit .env and fill in your Instagram credentials

Or set environment variables:

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