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)
.envand 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