colab mcp

The Problem

Google Colab notebooks need a local “MCP” (Multiplexed Control Protocol) server to forward code‑execution requests, subscription queries and assignment data. Without a ready‑to‑run server each integration must re‑implement the HTTP‑upgrade, authentication and websocket plumbing, which adds duplicated effort and hidden security gaps.

What This Does

The repository implements a minimal MCP server that can be started from the package entry point src/colab_mcp/__init__.py. Core responsibilities are split across five modules:

Module	Primary duties
`src/colab_mcp/auth.py`	`get_credentials()` reads a stored token (or refreshes it) and returns a `Credentials` object.
`src/colab_mcp/client.py`	`ColabProxyClient` builds HTTP requests, performs the actual network call (`_issue_request`) and handles the XSSI prefix.
`src/colab_mcp/runtime.py`	`ColabRuntimeTool` creates a runtime proxy that exposes `session`, `colab_prod_client`, `assignment`, and `kernel_client` properties.
`src/colab_mcp/session.py`	`ColabSessionProxy` manages the lifecycle of a Colab session (`connect_session`, `is_connected`).
`src/colab_mcp/websocket_server.py`	`ColabWebSocketServer` accepts websocket upgrades, validates the `origin` header and routes inbound messages to the runtime tools.

Tests under tests/ exercise each public API and the websocket handshake.

How It Is Wired

Execution starts at src/colab_mcp/__init__.py:main() (line 117). The call chain is:

main → main_async – asynchronous orchestrator.
main_async calls in order: - parse_args – builds a minimal CLI (no external flags currently). - init_logger – configures a console logger. - get_credentials (auth.py) – loads or refreshes an OAuth token, reading a file on disk. - ColabRuntimeTool (runtime.py) – constructs a runtime proxy object. - ColabSessionProxy (session.py) – creates a session object that may open a persistent connection. - start_proxy_server (websocket_server.py) – instantiates ColabWebSocketServer and begins listening. - cleanup – shuts down the server and session on exit.

The most‑used internal symbols are:

ColabWebSocketServer – invoked from 11 locations (the hub for inbound websocket traffic).
_issue_request – called 6 times from the client to perform HTTP calls.
is_connected – queried 5 times to guard session‑state decisions.

Outbound effects:

Network – ColabProxyClient._issue_request performs HTTPS calls (currently with verify=False).
Crypto/secret – the same client generates a UUID‑based token (uuid_to_web_safe_base64).
Filesystem – auth.py reads the cached token file and tests/auth_test.py writes temporary files.

No circular imports are present; each of the six Python modules is isolated, which keeps the dependency surface small but also leads to duplicated helper code (seven 6‑line repeats across __init__.py, auth.py, client.py, runtime.py, etc.). The websocket server contains a nesting depth of six, making the request‑validation logic harder to follow.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/colab-mcp
cd colab-mcp

# Install uv (required by the README)
pip install uv

# Run the server (mirrors the upstream usage example)
uvx git+https://github.com/moses-y/colab-mcp

The uvx command installs the package in an isolated environment and executes its entry point (main). No additional configuration files are shipped; the server expects a token file in the user’s home directory (handled by auth.get_credentials). If a custom token location is needed, modify auth.py accordingly.

Real‑World Use

A CI runner that needs to compile notebooks can start the MCP server locally, point the mcpServers.colab-mcp.command field in its mcp.json to the uvx invocation above, and then invoke Colab notebook APIs (e.g., GET /assignments) through the websocket endpoint ws://localhost:8080. The runner can reuse the same session across multiple notebook builds, reducing authentication latency.

Code Health & Issues

HIGH – Certificate verification disabled – src/colab_mcp/client.py sets verify = False in _issue_request. This accepts any TLS certificate, exposing traffic to MITM attacks.
HIGH – No CI pipeline – repository lacks .github/workflows/ or any build‑test automation despite 11 source files and a full test suite.
HIGH – Dependabot missing – only pyproject.toml is present; no Dependabot or Renovate configuration to keep dependencies patched.
MEDIUM – Duplicated code blocks – identical 6‑line snippets appear in at least seven places across the core modules, violating DRY principles.
MEDIUM – Deep nesting – src/colab_mcp/websocket_server.py reaches six levels of indentation, making future modifications error‑prone.

The Bottom Line

The repo delivers a functional MCP server with a clear module split and a complete test suite, making it a usable foundation for Colab integrations. However, security (TLS verification), maintainability (code duplication, deep nesting), and production readiness (CI, automated dependency updates) need immediate attention before the code can be considered safe for broader deployment. Engineers planning to adopt it should first address the high‑severity issues.