Instagram Download MCP Server

# ig-download-mcp 使用 [Instaloader](https://github.com/instaloader/instaloader) 實作的 Instagram MCP（Model Context Protocol）Server，讓 Claude / Claude Code / Codex 等 AI 助理可以下載 Instagram 內容。 ## 功能 - 下載貼文（圖片 / 影片 / Carousel） - 下載影片（Reels / IGTV / 影片貼文） - 下載 Stories（需要登入） - 下載 Highlights（需要登入） - 下載大頭貼 - 可選擇儲存 metadata（JSON）與 caption（文字檔） - 支援 `.env` / 環境變數設定帳密（避免在 tool 參數內傳遞） ## 需求 - Python >= 3.13 - [uv](https://github.com/astral-sh/uv) ## 快速開始 ### 1) 下載專案 ```bash git clone https://github.com/<YOUR_ORG_OR_USER>/ig-download-mcp.git cd ig-download-mcp ``` ### 2) 安裝依賴 ```bash uv venv uv sync ``` ### 3) 設定帳密（推薦） ```bash cp .env.example .env # Edit .env and fill in your Instagram credentials ``` ### 4) 啟動 MCP Server ```bash uv run ig-download-mcp ``` ## MCP 設定 請將 `/path/to/ig-download-mcp` 替換成你實際的安裝路徑。 ### Claude Desktop 編輯 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS；其他平台請使用對應的設定檔）： ```json { "mcpServers": { "ig-download-mcp": { "command": "uv", "args": ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"] } } } ``` ### Claude Code 編輯 `~/.claude.json`： ```json { "mcpServers": { "ig-download-mcp": { "command": "uv", "args": ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"] } } } ``` ### Codex（OpenAI） 編輯 `~/.codex/config.toml`： ```toml [mcp_servers.ig_download_mcp] command = "uv" args = ["--directory", "/path/to/ig-download-mcp", "run", "ig-download-mcp"] ``` ## 可用工具 | Tool | 說明 | 需要登入 | |------|------|----------| | `download_instagram_post` | 下載貼文（圖片/影片/Carousel） | 選填 | | `download_instagram_video` | 僅下載影片 | 選填 | | `download_instagram_stories` | 下載 Stories | 必填 | | `download_instagram_highlights` | 下載 Highlights | 必填 | | `download_instagram_profile_pic` | 下載大頭貼 | 選填 | ## 參數 ### `download_instagram_post` / `download_instagram_video` | 參數 | 型別 | 必填 | 說明 | |------|------|------|------| | `url` | string | 是 | Instagram `p/` / `reel/` / `tv/` URL | | `username` | string | 否 | IG 帳號（未提供時會讀取 `IG_USERNAME`） | | `password` | string | 否 | IG 密碼（未提供時會讀取 `IG_PASSWORD`） | | `save_metadata` | bool | 否 | 是否儲存 JSON metadata（預設 true） | | `save_caption` | bool | 否 | 是否儲存 caption 文字檔（預設 true） | | `download_root` | string | 否 | 覆寫下載根目錄（預設 `~/Downloads/instagram`） | ### `download_instagram_stories` / `download_instagram_highlights` | 參數 | 型別 | 必填 | 說明 | |------|------|------|------| | `username_target` | string | 是 | 目標 IG 使用者名稱 | | `highlight_title` | string | 否 | （Highlights）指定標題，不填則下載全部 | | `username` | string | 否 | IG 帳號（未提供時會讀取 `IG_USERNAME`） | | `password` | string | 否 | IG 密碼（未提供時會讀取 `IG_PASSWORD`） | | `download_root` | string | 否 | 覆寫下載根目錄（預設 `~/Downloads/instagram`） | ## 憑證設定 若不想建立 `.env`，也可以在 shell 設定環境變數： ```bash export IG_USERNAME="your_username" export IG_PASSWORD="your_password" ``` ## 重要提醒 - 本專案與 Instagram / Meta 無關聯；請遵守相關服務條款與法律規範，並自行承擔使用風險。 - Stories / Highlights 需要登入；未提供帳密會回傳錯誤。 - 若觸發 2FA 或 challenge 流程，Instaloader 可能會失敗並回傳錯誤。 - Instaloader 有內建速率限制；請避免高頻率大量下載。 ## License MIT | `username` | string | Yes | Your Instagram username | | `password` | string | Yes | Your Instagram password | | `highlight_title` | string | No | Filter by highlight title (highlights only) | | `download_root` | string | No | Override download directory | ### download_instagram_profile_pic | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `username_target` | string | Yes | Target Instagram username | | `username` | string | No | Instagram username (for HD quality) | | `password` | string | No | Instagram password | | `download_root` | string | No | Override download directory | ## Environment Variables | Variable | Description | |----------|-------------| | `IG_USERNAME` | Instagram username | | `IG_PASSWORD` | Instagram password | When set, credentials are used automatically without passing them as parameters. ## Usage Examples In a Claude conversation: ``` Download this Instagram post: https://www.instagram.com/p/ABC123/ ``` ``` Download @username's stories (Use my IG account: username=xxx, password=xxx) ``` ## FAQ ### Q: Why did the download fail? Possible reasons: - Instagram restricts unauthenticated access → Set up credentials - Rate limiting triggered → Wait and try again later - Content deleted or from a private account ### Q: Why is login required? Stories and Highlights require authentication to access. Profile pictures return HD quality when logged in. ### Q: Is 2FA supported? Currently not supported. If your account has 2FA enabled, consider using an app-specific password or temporarily disabling 2FA. ## Disclaimer **IMPORTANT NOTICE:** 1. **Unofficial Project**: This project is not affiliated with, authorized by, maintained by, or endorsed by Instagram, Meta, or any of their affiliates or subsidiaries. 2. **Use at Your Own Risk**: Using this tool may violate Instagram's Terms of Service. Your account may be subject to restrictions, suspension, or permanent termination. Users assume all risks associated with using this software. 3. **Personal Use Only**: This tool is intended solely for personal backup, research, or educational purposes. Do not use downloaded content for commercial purposes or unauthorized redistribution. 4. **Respect Copyright**: Downloaded content remains protected by the original creators' copyright. Please respect creators' rights. 5. **Data Security**: Your Instagram credentials are stored only in local configuration files and are never transmitted to any third-party servers. However, please secure your credentials appropriately. 6. **No Warranty**: This software is provided "as is" without any express or implied warranties of any kind. **By using this software, you acknowledge that you have read, understood, and agreed to the above disclaimer.** ## License MIT License ## Acknowledgments - [Instaloader](https://github.com/instaloader/instaloader) - Instagram download engine - [MCP](https://modelcontextprotocol.io/) - Model Context Protocol - [uv](https://github.com/astral-sh/uv) - Python package manager