mcp-server-cocalc-exec

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.
2. Open account settings and create/copy an API key.
3. Export your API key before starting the MCP server:

export COCALC_API_KEY="your_api_key"

Optional:

export COCALC_PROJECT_ID="existing_project_id"

Installation

pip install mcp-server-cocalc-exec

Or run directly with uvx:

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

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

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

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

cocalc_stop_project()

MCP Client Configuration

Claude Desktop

Add this to your claude_desktop_config.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