mcp-server-lightning-exec

MCP server for executing Python code on Lightning.ai GPU Studios. It enables any MCP-compatible assistant to run CUDA / ML workloads remotely on Lightning machines like T4, L4, A10G, A100, or CPU — without requiring local GPU hardware.

Features

• lightning_execute: Execute inline Python code on a Lightning Studio machine.

• lightning_execute_file: Execute a local .py file on Lightning.

• lightning_execute_notebook: Execute code and download generated artifacts (images, models, CSVs, etc.).

• lightning_stop_studio: Stop the active Studio to conserve GPU hours.

Related MCP server: mcp-server-colab-exec

Prerequisites

• Python 3.10+

• A Lightning.ai account

• A Lightning API key and your Lightning user ID

Lightning API setup

1. Sign in to Lightning.ai.

2. Open account settings and create/copy an API key.

3. Copy your Lightning user ID from your account/workspace profile.

4. Export credentials before starting the MCP server:

export LIGHTNING_USER_ID="your_user_id"
export LIGHTNING_API_KEY="your_api_key"

Optional:

export LIGHTNING_TEAMSPACE="default"
export LIGHTNING_STUDIO_NAME="mcp-exec"

Installation

pip install mcp-server-lightning-exec

Or run directly with uvx:

uvx mcp-server-lightning-exec

Configuration

Tools and Usage

lightning_execute

Execute inline Python code on a Lightning machine.

Parameters

• code (string, required): Python code to execute.

• machine (string, default "T4"): One of T4, L4, A10G, A100, CPU.

• timeout (int, default 300): Max execution time in seconds.

Example

lightning_execute(
    code="import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))",
    machine="L4",
    timeout=300,
)

lightning_execute_file

Execute a local Python file on a Lightning machine.

Parameters

• file_path (string, required): Local path to .py file.

• machine (string, default "T4")

• timeout (int, default 300)

Example

lightning_execute_file(
    file_path="./train.py",
    machine="A10G",
    timeout=600,
)

lightning_execute_notebook

Execute code and download generated artifacts as a zip + extracted files.

Parameters

• code (string, required)

• output_dir (string, required): Local folder to save artifacts.

• machine (string, default "T4")

• timeout (int, default 300)

Example

lightning_execute_notebook(
    code="import torch; torch.save({'x': 1}, '/tmp/model.pt')",
    output_dir="./outputs",
    machine="T4",
)

lightning_stop_studio

Stop the current Studio to avoid idle GPU usage.

Example

lightning_stop_studio()

MCP Client Configuration

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "lightning-exec": {
      "command": "mcp-server-lightning-exec",
      "env": {
        "LIGHTNING_USER_ID": "your_user_id",
        "LIGHTNING_API_KEY": "your_api_key",
        "LIGHTNING_TEAMSPACE": "default",
        "LIGHTNING_STUDIO_NAME": "mcp-exec"
      }
    }
  }
}

Architecture

Execution flow:

1. MCP tool receives code/file request.

2. Server wraps input into cell markers for per-cell parsing.

3. Runtime loads Lightning config from env and gets/creates a cached Studio.

4. Runtime starts Studio, switches machine, and runs a wrapper script remotely.

5. Wrapper captures stdout, stderr, and exit_code with explicit markers.

6. Server parses markers into structured JSON and returns to the MCP client.

7. Artifact tool additionally scans runtime outputs, zips them, and returns base64 payload for local extraction.

Comparison with mcp-server-colab-exec

License

MIT