Modal MCP Server

Instructions

Download files from a Modal volume.

Args:
    volume_name: Name of the Modal volume to download from.
    remote_path: Path to the file or directory in the volume to download.
    local_destination: Local path to save the downloaded file(s). Defaults to current directory.
                     Use "-" to write file contents to stdout.
    force: If True, overwrite existing files. Defaults to False.

Returns:
    A dictionary containing the result of the download operation.

Raises:
    Exception: If the download operation fails for any reason.

Implementation Reference

• src/modal_mcp/server.py:268-311 (handler)

  The primary handler function for the 'get_modal_volume_file' tool. It constructs and executes the 'modal volume get' command to download files or directories from a Modal volume to a local destination, handling success/error responses and logging.

  @mcp.tool()
  async def get_modal_volume_file(volume_name: str, remote_path: str, local_destination: str = ".", force: bool = False) -> dict[str, Any]:
      """
      Download files from a Modal volume.
  
      Args:
          volume_name: Name of the Modal volume to download from.
          remote_path: Path to the file or directory in the volume to download.
          local_destination: Local path to save the downloaded file(s). Defaults to current directory.
                           Use "-" to write file contents to stdout.
          force: If True, overwrite existing files. Defaults to False.
  
      Returns:
          A dictionary containing the result of the download operation.
  
      Raises:
          Exception: If the download operation fails for any reason.
      """
      try:
          command = ["modal", "volume", "get"]
          if force:
              command.append("--force")
          command.extend([volume_name, remote_path, local_destination])
          
          result = run_modal_command(command)
          response = {
              "success": result["success"],
              "command": result["command"]
          }
          
          if not result["success"]:
              response["error"] = f"Failed to download {remote_path}: {result.get('error', 'Unknown error')}"
          else:
              response["message"] = f"Successfully downloaded {remote_path} from volume {volume_name}"
              
          if result.get("stdout"):
              response["stdout"] = result["stdout"]
          if result.get("stderr"):
              response["stderr"] = result["stderr"]
              
          return response
      except Exception as e:
          logger.error(f"Failed to download from Modal volume: {e}")
          raise

• src/modal_mcp/server.py:268-268 (registration)

  The @mcp.tool() decorator registers the get_modal_volume_file function as an available MCP tool in the FastMCP server.

  @mcp.tool()

• src/modal_mcp/server.py:15-41 (helper)

  Helper function used by get_modal_volume_file to execute Modal CLI commands via subprocess, capturing output and standardizing success/error responses.

  def run_modal_command(command: list[str], uv_directory: str = None) -> dict[str, Any]:
      """Run a Modal CLI command and return the result"""
      try:
          # uv_directory is necessary for modal deploy, since deploying the app requires the app to use the uv venv
          command = (["uv", "run", f"--directory={uv_directory}"] if uv_directory else []) + command
          logger.info(f"Running command: {' '.join(command)}")
          result = subprocess.run(
              command,
              capture_output=True,
              text=True,
              check=True
          )
          return {
              "success": True,
              "stdout": result.stdout,
              "stderr": result.stderr,
              "command": ' '.join(command)
          }
      except subprocess.CalledProcessError as e:
          return {
              "success": False,
              "error": str(e),
              "stdout": e.stdout,
              "stderr": e.stderr,
              "command": ' '.join(command)
          }