Modal MCP Server

Instructions

Copy files within a Modal volume. Can copy a source file to a destination file
or multiple source files to a destination directory.

Args:
    volume_name: Name of the Modal volume to perform copy operation in.
    paths: List of paths for the copy operation. The last path is the destination,
          all others are sources. For example: ["source1.txt", "source2.txt", "dest_dir/"]

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

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

Implementation Reference

• src/modal_mcp/server.py:135-178 (handler)

  The handler function for the 'copy_modal_volume_files' tool, decorated with @mcp.tool() for registration. It validates input, runs 'modal volume cp' via run_modal_command helper, and formats the response.

  @mcp.tool()
  async def copy_modal_volume_files(volume_name: str, paths: List[str]) -> dict[str, Any]:
      """
      Copy files within a Modal volume. Can copy a source file to a destination file
      or multiple source files to a destination directory.
  
      Args:
          volume_name: Name of the Modal volume to perform copy operation in.
          paths: List of paths for the copy operation. The last path is the destination,
                all others are sources. For example: ["source1.txt", "source2.txt", "dest_dir/"]
  
      Returns:
          A dictionary containing the result of the copy operation.
  
      Raises:
          Exception: If the copy operation fails for any reason.
      """
      if len(paths) < 2:
          return {
              "success": False,
              "error": "At least one source and one destination path are required"
          }
  
      try:
          result = run_modal_command(["modal", "volume", "cp", volume_name] + paths)
          response = {
              "success": result["success"],
              "command": result["command"]
          }
          
          if not result["success"]:
              response["error"] = f"Failed to copy files: {result.get('error', 'Unknown error')}"
          else:
              response["message"] = f"Successfully copied files in 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 copy files in Modal volume: {e}")
          raise

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

  Shared helper function that executes Modal CLI commands using subprocess and returns structured success/error results with stdout/stderr.

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