What is Modal Mcp Server

modal-mcp-server is an MCP server implementation designed for managing Modal applications and interacting with Modal volumes from within the Cursor environment.

Use cases

Use cases include managing file operations within Modal volumes, deploying applications that require dependency management through ‘uv’, and facilitating interactions with Modal’s storage capabilities.

How to use

To use modal-mcp-server, clone the repository, install dependencies using the ‘uv’ package manager, and configure it in your Cursor settings by adding the appropriate command and arguments in the mcp.json file.

Key features

Key features include listing Modal volumes, listing volume contents, copying files within Modal volumes, and removing files or directories from Modal volumes.

Where to use

modal-mcp-server is primarily used in software development environments where Modal applications are deployed and managed, particularly in projects that utilize the Cursor platform.

Modal MCP Server

An MCP server implementation for interacting with Modal volumes and deploying Modal applications from within Cursor.

Installation

1. Clone this repository:

git clone https://github.com/smehmood/modal-mcp-server.git
cd modal-mcp-server

2. Install dependencies using uv:

uv sync

Configuration

To use this MCP server in Cursor, add the following configuration to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "modal-mcp-server": {
      "command": "uv",
      "args": [
        "--project",
        "/path/to/modal-mcp-server",
        "run",
        "/path/to/modal-mcp-server/src/modal_mcp/server.py"
      ]
    }
  }
}

Replace /path/to/modal-mcp-server with the absolute path to your cloned repository.

Requirements

• Python 3.11 or higher
• uv package manager
• Modal CLI configured with valid credentials
• For Modal deploy support:
  • Project being deployed must use uv for dependency management
  • Modal must be installed in the project’s virtual environment

Supported Tools

Modal Volume Operations

1. List Modal Volumes (list_modal_volumes)

   • Lists all Modal volumes in your environment
   • Returns JSON-formatted volume information
   • Parameters: None

2. List Volume Contents (list_modal_volume_contents)

   • Lists files and directories in a Modal volume
   • Parameters:
     • volume_name: Name of the Modal volume
     • path: Path within volume (default: “/”)

3. Copy Files (copy_modal_volume_files)

   • Copies files within a Modal volume
   • Parameters:
     • volume_name: Name of the Modal volume
     • paths: List of paths where last path is destination
   • Example: ["source.txt", "dest.txt"] or ["file1.txt", "file2.txt", "dest_dir/"]

4. Remove Files (remove_modal_volume_file)

   • Deletes a file or directory from a Modal volume
   • Parameters:
     • volume_name: Name of the Modal volume
     • remote_path: Path to file/directory to delete
     • recursive: Boolean flag for recursive deletion (default: false)

5. Upload Files (put_modal_volume_file)

   • Uploads a file or directory to a Modal volume
   • Parameters:
     • volume_name: Name of the Modal volume
     • local_path: Path to local file/directory to upload
     • remote_path: Path in volume to upload to (default: “/”)
     • force: Boolean flag to overwrite existing files (default: false)

6. Download Files (get_modal_volume_file)

   • Downloads files from a Modal volume
   • Parameters:
     • volume_name: Name of the Modal volume
     • remote_path: Path to file/directory in volume to download
     • local_destination: Local path to save downloaded files (default: current directory)
     • force: Boolean flag to overwrite existing files (default: false)
   • Note: Use “-” as local_destination to write file contents to stdout

Modal Deployment

1. Deploy Modal App (deploy_modal_app)
   • Deploys a Modal application
   • Parameters:
     • absolute_path_to_app: Absolute path to the Modal application file
   • Note: The project containing the Modal app must:
     • Use uv for dependency management
     • Have the modal CLI installed in its virtual environment

Response Format

All tools return responses in a standardized format, with slight variations depending on the operation type:

# JSON operations (list volumes, list contents):
{
    "success": True,
    "data": {...}  # JSON data from Modal CLI
}

# File operations (put, get, copy, remove):
{
    "success": True,
    "message": "Operation successful message",
    "command": "executed command string",
    "stdout": "command output",  # if any
    "stderr": "error output"     # if any
}

# Error case (all operations):
{
    "success": False,
    "error": "Error message describing what went wrong",
    "command": "executed command string",  # for file operations
    "stdout": "command output",  # if available
    "stderr": "error output"     # if available
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.