# 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](https://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:

```bash
export LIGHTNING_USER_ID="your_user_id"
export LIGHTNING_API_KEY="your_api_key"
```

Optional:

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

## Installation

```bash
pip install mcp-server-lightning-exec
```

Or run directly with `uvx`:

```bash
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**

```python
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**

```python
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**

```python
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**

```python
lightning_stop_studio()
```

## MCP Client Configuration

### Claude Desktop

Add this to your `claude_desktop_config.json`:

```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