Instagram Download MCP Server

Instructions

Implementation Reference

• src/ig_download_mcp/server.py:505-612 (handler)

  The primary handler function for the 'download_instagram_highlights' tool. It logs into Instagram using provided credentials, retrieves highlights for the target user (optionally filtered by title), downloads the story items from each highlight, and returns a structured result with paths to downloaded files.
  @mcp.tool() def download_instagram_highlights( username_target: str, highlight_title: str | None = None, username: str | None = None, password: str | None = None, download_root: str | None = None, ) -> dict[str, Any]: """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. """ try: target_username = username_target.strip() if not target_username: raise ValueError("username_target must not be empty.") title_filter = highlight_title.strip() if highlight_title else None target_root = _resolve_download_root(download_root) loader = _build_instaloader( target_root, download_pictures=True, download_videos=True, save_metadata=False, save_caption=False, ) user, pwd = _resolve_credentials(username, password) _require_login(user, pwd, "highlights") _login_if_needed(loader, user, pwd) base_username = target_username.lower() profile = instaloader.Profile.from_username( loader.context, base_username, ) results: list[dict[str, Any]] = [] for highlight in loader.get_highlights(profile): if title_filter and ( highlight.title.strip().casefold() != title_filter.casefold() ): continue safe_title = _sanitize_target_component(highlight.title) highlight_dirname = ( f"{base_username}_highlight_{safe_title}_{highlight.unique_id}" ) download_dir = target_root / highlight_dirname before = _snapshot_files(download_dir) num_items = 0 num_downloaded = 0 for item in highlight.get_items(): num_items += 1 if loader.download_storyitem(item, target=highlight_dirname): num_downloaded += 1 after = _snapshot_files(download_dir) downloaded_files = (after - before) or after results.append( { "title": highlight.title, "unique_id": highlight.unique_id, "download_dir": str(download_dir), "num_items": num_items, "num_downloaded": num_downloaded, "image_files": _collect_paths_by_suffixes( downloaded_files, {".jpg", ".jpeg", ".png", ".webp"}, ), "video_files": _collect_paths_by_suffixes( downloaded_files, {".mp4"}, ), } ) if title_filter and not results: raise ValueError( "No highlights matched the given highlight_title." ) return { "success": True, "username_target": target_username, "highlight_title": title_filter, "highlights": results, } except instaloader.exceptions.InstaloaderException as exc: return { "success": False, "error": f"Instaloader error: {exc.__class__.__name__}: {exc}", } except Exception as exc: return {"success": False, "error": str(exc)}
• src/ig_download_mcp/server.py:505-505 (registration)

  Registers the 'download_instagram_highlights' tool with the FastMCP server instance using the @mcp.tool() decorator.
  @mcp.tool()
• src/ig_download_mcp/server.py:24-31 (helper)

  Helper function to resolve the download root directory, defaulting to ~/Downloads/instagram if not provided.
  def _resolve_download_root(download_root: str | None) -> Path: if download_root is None: return DEFAULT_DOWNLOAD_ROOT cleaned = download_root.strip() if not cleaned: return DEFAULT_DOWNLOAD_ROOT return Path(cleaned).expanduser()
• src/ig_download_mcp/server.py:60-81 (helper)

  Helper to create and configure an Instaloader instance for downloading.
  def _build_instaloader( download_root: Path, download_pictures: bool = False, download_videos: bool = True, save_metadata: bool = False, save_caption: bool = False, ) -> instaloader.Instaloader: dirname_pattern = str(download_root / "{target}") post_metadata_txt_pattern = "{caption}" if save_caption else "" return instaloader.Instaloader( quiet=True, dirname_pattern=dirname_pattern, download_pictures=download_pictures, download_videos=download_videos, download_video_thumbnails=False, download_geotags=False, download_comments=False, save_metadata=save_metadata, compress_json=False, post_metadata_txt_pattern=post_metadata_txt_pattern, )
• src/ig_download_mcp/server.py:97-102 (helper)

  Helper to normalize credential strings, stripping whitespace.
  def _normalize_credential(value: str | None) -> str | None: if value is None: return None stripped = value.strip() return stripped if stripped else None