Instagram Download MCP Server

Instructions

Implementation Reference

• src/ig_download_mcp/server.py:290-359 (handler)

  The @mcp.tool()-decorated function implementing the core logic of the 'download_instagram_post' tool. It extracts the shortcode from the URL, sets up Instaloader, handles login, downloads the post media, and returns paths to downloaded files.
  @mcp.tool() def download_instagram_post( url: str, include_videos: bool = True, save_metadata: bool = True, save_caption: bool = True, username: str | None = None, password: str | None = None, download_root: str | None = None, ) -> dict[str, Any]: """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. """ try: shortcode = extract_shortcode(url) target_root = _resolve_download_root(download_root) loader = _build_instaloader( target_root, download_pictures=True, download_videos=include_videos, save_metadata=save_metadata, save_caption=save_caption, ) user, pwd = _resolve_credentials(username, password) _login_if_needed(loader, user, pwd) download_dir, downloaded_files = _download_post_for_shortcode( loader, shortcode, target_root, ) image_files = _collect_paths_by_suffixes( downloaded_files, {".jpg", ".jpeg", ".png", ".webp"}, ) video_files = _collect_paths_by_suffixes(downloaded_files, {".mp4"}) metadata_files = _collect_paths_by_suffixes( downloaded_files, {".json"}, ) caption_files = _collect_paths_by_suffixes( downloaded_files, {".txt"}, ) return { "success": True, "shortcode": shortcode, "download_dir": str(download_dir), "image_files": image_files, "video_files": video_files, "metadata_files": metadata_files, "caption_files": caption_files, } 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)}