mcp-server-lightning-exec

<!-- mcp-name: io.github.pdwi2020/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.

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

Environment Variable	Required	Default	Description
LIGHTNING_USER_ID	Yes	—	Lightning.ai user identifier used for SDK authentication
LIGHTNING_API_KEY	Yes	—	Lightning.ai API key
LIGHTNING_TEAMSPACE	No	default	Teamspace where the Studio is created/reused
LIGHTNING_STUDIO_NAME	No	mcp-exec	Studio name to create/reuse across requests

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

Aspect	mcp-server-lightning-exec	mcp-server-colab-exec
Backend	Lightning.ai Studios	Google Colab runtimes
Auth model	LIGHTNING_USER_ID + LIGHTNING_API_KEY	OAuth2 browser flow + token cache
Runtime lifecycle	Persistent named Studio (create/reuse/start/stop)	Ephemeral runtime allocate/unassign per execution
Machine options	T4, L4, A10G, A100, CPU	T4, L4
Stop control	Explicit lightning_stop_studio tool	Runtime auto-released after execution
Artifact handling	Base64 zip extraction via notebook tool	Base64 zip extraction via notebook tool

License

MIT