Skip to main content
Glama
Instagram Download MCP Server

Instagram Download MCP Server

by KaiQin04

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
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

Available Tools

5 tools
download_instagram_highlightsB

Download Instagram highlights for a target user.

Note: This feature requires login.

Args: username_target: Target Instagram username. highlight_title: Optional highlight title filter. username: Instagram username for authenticated access. password: Instagram password for authenticated access. download_root: Optional override for download directory.

Returns: A JSON-serializable dict containing download results.

Inputs: username_target (required), highlight_title, username, password, +1 more. Returns: object

download_instagram_postA

Download an Instagram post's media files to the local filesystem.

Args: url: Instagram post/reel/tv URL. include_videos: Whether to download videos alongside pictures. save_metadata: Save JSON metadata files when available. save_caption: Save caption into a text file when available. username: Optional Instagram username for authenticated access. password: Optional Instagram password for authenticated access. download_root: Optional override for download directory.

Returns: A JSON-serializable dict containing download results.

Inputs: url (required), include_videos, save_metadata, save_caption, +3 more. Returns: object

download_instagram_profile_picB

Download an Instagram profile picture to the local filesystem.

Args: username_target: Target Instagram username. username: Optional Instagram username for authenticated access. password: Optional Instagram password for authenticated access. download_root: Optional override for download directory.

Returns: A JSON-serializable dict containing download results.

Inputs: username_target (required), username, password, download_root. Returns: object

download_instagram_storiesA

Download Instagram stories for a target user.

Note: This feature requires login.

Args: username_target: Target Instagram username. username: Instagram username for authenticated access. password: Instagram password for authenticated access. download_root: Optional override for download directory.

Returns: A JSON-serializable dict containing download results.

Inputs: username_target (required), username, password, download_root. Returns: object

download_instagram_videoA

Download an Instagram video's media files to the local filesystem.

Args: url: Instagram post/reel/tv URL. username: Optional Instagram username for authenticated access. password: Optional Instagram password for authenticated access. save_metadata: Save JSON metadata files when available. save_caption: Save caption into a text file when available. download_root: Optional override for download directory.

Returns: A JSON-serializable dict containing download results.

Inputs: url (required), username, password, save_metadata, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    The tools are mostly distinct with clear purposes: highlights, posts, profile pictures, stories, and videos. However, there is some overlap between download_instagram_post and download_instagram_video, as both handle posts/reels/tv URLs, which could cause confusion about which to use for video content. The descriptions help clarify, but the boundaries are not perfectly clear.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with 'download_instagram_' as a prefix, followed by the specific target (e.g., highlights, post, profile_pic, stories, video). This uniformity makes the tool set predictable and easy to understand, with no deviations in naming style.

    Tool Count5/5

    With 5 tools, this server is well-scoped for its purpose of downloading various Instagram content types. Each tool serves a distinct function (highlights, posts, profile pictures, stories, videos), and the count is neither too sparse nor excessive, fitting typical expectations for a focused download utility.

    Completeness4/5

    The tool set covers key Instagram content types for downloading: highlights, posts, profile pictures, stories, and videos, providing good coverage for the domain. A minor gap is the lack of a tool for downloading multiple posts or feeds, which might be useful for batch operations, but agents can work around this by iterating with the existing tools.

    Related MCP Connectors