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