Modal MCP Server

Instructions

Upload a file or directory to a Modal volume.

Args:
    volume_name: Name of the Modal volume to upload to.
    local_path: Path to the local file or directory to upload.
    remote_path: Path in the volume to upload to. Defaults to root ("/").
                If ending with "/", it's treated as a directory and the file keeps its name.
    force: If True, overwrite existing files. Defaults to False.

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

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

Implementation Reference

• src/modal_mcp/server.py:223-266 (handler)

  The handler function for the 'put_modal_volume_file' tool. It is decorated with @mcp.tool() for registration and implements the logic to upload a local file or directory to a Modal volume using the 'modal volume put' command via subprocess.

  @mcp.tool()
  async def put_modal_volume_file(volume_name: str, local_path: str, remote_path: str = "/", force: bool = False) -> dict[str, Any]:
      """
      Upload a file or directory to a Modal volume.
  
      Args:
          volume_name: Name of the Modal volume to upload to.
          local_path: Path to the local file or directory to upload.
          remote_path: Path in the volume to upload to. Defaults to root ("/").
                      If ending with "/", it's treated as a directory and the file keeps its name.
          force: If True, overwrite existing files. Defaults to False.
  
      Returns:
          A dictionary containing the result of the upload operation.
  
      Raises:
          Exception: If the upload operation fails for any reason.
      """
      try:
          command = ["modal", "volume", "put"]
          if force:
              command.append("-f")
          command.extend([volume_name, local_path, remote_path])
          
          result = run_modal_command(command)
          response = {
              "success": result["success"],
              "command": result["command"]
          }
          
          if not result["success"]:
              response["error"] = f"Failed to upload {local_path}: {result.get('error', 'Unknown error')}"
          else:
              response["message"] = f"Successfully uploaded {local_path} to {volume_name}:{remote_path}"
              
          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 upload to Modal volume: {e}")
          raise

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

  Helper function used by the tool to execute Modal CLI commands via subprocess and standardize the output.

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