# 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