minimodal

A simple command-line tool to compile and run CUDA kernels on local GPUs or Modal cloud infrastructure, now with MCP (Model Context Protocol) server support.

Features:

• Automatic GPU detection and architecture mapping
• Seamless fallback to Modal cloud GPUs when local GPU isn't available
• Support for include directories and custom nvcc flags
• Works with Modal GPU naming convention (A10G, H100, B200, etc.)
• MCP server enabling AI agents to compile and run CUDA code

Installation

uv pip install minimodal

Or install from source:

cd minimodal
uv pip install -e .

Usage

Basic usage (defaults to A10G):

minimodal v1.cu

With a specific GPU:

minimodal v1.cu --gpu H100

With include directories:

minimodal v1.cu --gpu B200 -I ./includes

With execution arguments:

minimodal v1.cu --gpu A100 --exec-args "--N 2097152 --warmup 5"

With custom nvcc flags:

minimodal kernel.cu --gpu H100 -I ./includes --nvcc-flags "-O3 --ptxas-options=-v"

Supported GPUs

The tool automatically detects GPU architecture for common GPU models:

• H100 / H800 → sm_90
• A100 / A800 → sm_80
• A10G → sm_86
• B200 / B100 → sm_100a
• RTX4090 → sm_89
• RTX3090 / RTX3080 → sm_86
• V100 → sm_70
• T4 → sm_75

You can also specify the architecture directly using --arch:

minimodal kernel.cu --arch 100a

Options

• --gpu, -g: GPU name (e.g., A10G, H100, B200, A100) or architecture (e.g., 100a, 90). Default: A10G
• --include-dir, -I: Include directory. Can be specified multiple times.
• --exec-args: Arguments to pass to the compiled CUDA executable.
• --arch: Override architecture. If not specified, inferred from --gpu.
• --output, -o: Output executable path. If not specified, uses temporary file.
• --keep-binary: Keep the compiled binary after execution.
• --nvcc-flags: Additional flags to pass to nvcc (e.g., '-O3 --ptxas-options=-v').

MCP Server Usage

The minimodal package includes an MCP (Model Context Protocol) server that enables AI agents to compile and run CUDA kernels. This allows you to use minimodal with tools like Claude Desktop, Cursor, or other MCP-compatible AI assistants.

Starting the MCP Server

Start the server with stdio transport (default):

minimodal-mcp

Start the server with SSE transport (for web clients):

minimodal-mcp --transport sse

Start with SSE on a custom port:

minimodal-mcp --transport sse --port 9000

Configuring Claude Desktop

1. Add the following configuration to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "minimodal": {
      "command": "minimodal-mcp",
      "args": []
    }
  }
}

2. Restart Claude Desktop

3. The minimodal tools will now be available in your Claude conversations

Available MCP Tools

The MCP server exposes the following tools:

• compile_cuda: Compile and run a CUDA kernel file
• list_gpus: List available local and Modal cloud GPUs
• get_gpu_architecture: Get CUDA architecture for a specific GPU name

Example MCP Usage

Once configured with an AI assistant, you can use natural language to compile CUDA code:

• "Compile and run the vector_add.cu file on an H100 GPU"
• "Check what GPUs are available"
• "What architecture does an A10G GPU use?"
• "Compile kernel.cu with include directories include/, optimization flags, and keep the binary"

Requirements

• CUDA toolkit with nvcc compiler
• NVIDIA GPU drivers
• nvidia-smi command-line tool
• Modal account and API key (for cloud GPU usage)

Examples

Compile and run a CUDA kernel (defaults to A10G):

minimodal v1.cu

Compile and run on a specific GPU:

minimodal v1.cu --gpu H100

Compile with multiple include directories:

minimodal kernel.cu --gpu B200 -I ./includes -I ./headers

Run with custom arguments:

minimodal benchmark.cu --gpu A100 --exec-args "--size 4096 --iterations 100"

Development

To develop locally:

git clone <repository-url>
cd minimodal
uv pip install -e .

Publishing to PyPI

# Build distribution
uv build

# Upload to PyPI
uv pip install twine
twine upload dist/*

License

MIT