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

Instagram Download MCP Server