# mcp-server-cocalc-exec

<!-- mcp-name: io.github.pdwi2020/mcp-server-cocalc-exec -->

MCP server for executing Python code on CoCalc cloud projects. It enables any MCP-compatible assistant to run Python and machine-learning workloads remotely on CoCalc infrastructure without local GPU requirements.

## Features

- `cocalc_execute`: Execute inline Python code on a CoCalc project.
- `cocalc_execute_file`: Execute a local `.py` file on CoCalc.
- `cocalc_execute_notebook`: Execute code and download generated artifacts (images, models, CSVs, etc.).
- `cocalc_stop_project`: Stop the active project to conserve cloud resources.

## Prerequisites

- Python 3.10+
- A CoCalc account
- A CoCalc API key

### CoCalc API setup

1. Sign in to [CoCalc](https://cocalc.com/).
2. Open account settings and create/copy an API key.
3. Export your API key before starting the MCP server:

```bash
export COCALC_API_KEY="your_api_key"
```

Optional:

```bash
export COCALC_PROJECT_ID="existing_project_id"
```

## Installation

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

Or run directly with `uvx`:

```bash
uvx mcp-server-cocalc-exec
```

## Configuration

| Environment Variable   | Required | Default        | Description |
|------------------------|----------|----------------|-------------|
| `COCALC_API_KEY`       | Yes      | -              | CoCalc API key used for REST authentication |
| `COCALC_PROJECT_ID`    | No       | auto-create    | Existing CoCalc project id to reuse across requests |

## Tools and Usage

### `cocalc_execute`

Execute inline Python code on CoCalc.

**Parameters**

- `code` (string, required): Python code to execute.
- `timeout` (int, default `300`): Max execution time in seconds.

**Example**

```python
cocalc_execute(
    code="import platform; print(platform.python_version())",
    timeout=300,
)
```

### `cocalc_execute_file`

Execute a local Python file on CoCalc.

**Parameters**

- `file_path` (string, required): Local path to `.py` file.
- `timeout` (int, default `300`)

**Example**

```python
cocalc_execute_file(
    file_path="./train.py",
    timeout=600,
)
```

### `cocalc_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.
- `timeout` (int, default `300`)

**Example**

```python
cocalc_execute_notebook(
    code="open('/tmp/hello.txt', 'w').write('hello from cocalc')",
    output_dir="./outputs",
    timeout=300,
)
```

### `cocalc_stop_project`

Stop the current CoCalc project runtime to avoid idle usage.

**Example**

```python
cocalc_stop_project()
```

## MCP Client Configuration

### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cocalc-exec": {
      "command": "mcp-server-cocalc-exec",
      "env": {
        "COCALC_API_KEY": "your_api_key",
        "COCALC_PROJECT_ID": "optional_existing_project_id"
      }
    }
  }
}
```

## Architecture

Execution flow:

1. MCP tool receives code/file request.
2. Server wraps input into cell markers for per-cell parsing.
3. Runtime loads CoCalc config from env and gets/creates a cached project id.
4. Runtime starts project (if needed) via CoCalc REST API.
5. Runtime executes `python3 -c "<wrapped_code>"` through `projects/exec`.
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.

## License

MIT