XLMCP

Collection of MCP servers, agents, and extensions for quantitative development/research with Qubx.

XLMCP - Jupyter MCP Server

XLMCP gives Claude Code tools to interact with Jupyter notebooks running on JupyterHub or a standalone Jupyter Server — read/edit cells, manage kernels, and execute code.

Note: knowledge/RAG search and project-management tools were moved out of xlmcp (to the crtx-server project) as of v0.5.0. xlmcp is now a focused Jupyter server.

Total Tools: 17 (Jupyter notebook, kernel, and execution operations)

Quick Reference

Jupyter Tools (17)

# - Notebook operations
await jupyter_list_notebooks(directory="")
await jupyter_find_notebook(filename)
await jupyter_get_notebook_info(notebook_path)
await jupyter_read_cell(notebook_path, cell_index)
await jupyter_read_all_cells(notebook_path)
await jupyter_append_cell(notebook_path, source, cell_type="code")
await jupyter_insert_cell(notebook_path, cell_index, source, cell_type="code")
await jupyter_update_cell(notebook_path, cell_index, source)
await jupyter_delete_cell(notebook_path, cell_index)

# - Kernel operations
await jupyter_list_kernels()
await jupyter_start_kernel(kernel_name="python3")
await jupyter_stop_kernel(kernel_id)
await jupyter_restart_kernel(kernel_id)
await jupyter_interrupt_kernel(kernel_id)

# - Execution
await jupyter_execute_code(kernel_id, code, timeout=None)
await jupyter_connect_notebook(notebook_path)
await jupyter_execute_cell(notebook_path, cell_index, timeout=None)

Connecting to a notebook's kernel

jupyter_connect_notebook resolves the kernel for a notebook by normalised path match (absolute / server-relative / VS Code -jvsc-<uuid> synthetic paths all map to the same notebook), so it reuses the live kernel instead of spawning duplicates. Its status:

• existing — one live kernel matched; use its kernel_id.
• ambiguous — several matched; pick a kernel_id from candidates (or stop the extras).
• created — none matched, a new session was made.

Every response includes attach_url — paste it into VS Code → Select Kernel → Existing Jupyter Server to join the same kernel from the editor (the token authenticates directly to the single-user server, bypassing the Hub login dialog).

Installation

From PyPI (Recommended)

pip install xlmcp
# - or using uv
uv pip install xlmcp

From Source

cd ~/devs/aix
uv pip install -e .

Configuration

Environment Setup

1. Copy env.example to .env:

cp env.example .env

2. Edit .env and configure:

Jupyter Server (Required):

JUPYTER_SERVER_URL=http://localhost:8888
JUPYTER_API_TOKEN=your-token-here
JUPYTER_NOTEBOOK_DIR=~/
JUPYTER_ALLOWED_DIRS=~/projects,~/devs,~/research

MCP Server (Optional, defaults provided):

MCP_TRANSPORT=stdio
MCP_HTTP_PORT=8765
MCP_MAX_OUTPUT_TOKENS=25000

Get a Jupyter API Token

• JupyterHub: Admin panel → User → New API Token
• Jupyter Server: jupyter server list shows the token

Global Setup (Multi-Project Environments)

For users with multiple projects and virtual environments:

1. Install xlmcp Globally

# Install in system Python (not in project venvs)
pip install xlmcp
# or: /usr/bin/python -m pip install xlmcp

2. Create Central Configuration

mkdir -p ~/.aix/xlmcp
cp env.example ~/.aix/xlmcp/.env
nano ~/.aix/xlmcp/.env   # Add your JUPYTER_API_TOKEN

xlmcp finds config in this order:

1. .env in the current directory (project-specific override)
2. ~/.aix/xlmcp/.env (global default) ← Recommended
3. Environment variables

3. Register with Claude Code

cd /path/to/project
source .venv/bin/activate            # if using a venv
claude mcp add --transport stdio xlmcp -- /usr/bin/python -m xlmcp.server

Replace /usr/bin/python with your system Python (which python outside any venv).

Verify:

claude mcp list
# Should show: xlmcp: /usr/bin/python -m xlmcp.server - ✓ Connected

Simple Setup (Single Project / Quick Start)

pip install xlmcp
cp env.example .env
nano .env                            # Add JUPYTER_API_TOKEN
claude mcp add --transport stdio xlmcp -- python -m xlmcp.server

Or with environment variables (no .env file needed):

claude mcp add \
  -e JUPYTER_SERVER_URL=http://localhost:8888 \
  -e JUPYTER_API_TOKEN=your-token \
  --transport stdio \
  xlmcp \
  -- python -m xlmcp.server

The -- before python separates MCP options from the server command.

XLMCP CLI

xlmcp start      # Start server in background
xlmcp status     # Show server status
xlmcp ls         # List available tools
xlmcp kernels    # List active Jupyter kernels
xlmcp restart    # Restart server
xlmcp stop       # Stop server

Usage Examples

> Connect to my notebook and execute the first cell
> List all notebooks in research/momentum/
> Execute code: print("Hello from Jupyter!")
> Restart the kernel for research/analysis.ipynb

Transport Modes

stdio (default) — for local Claude Code:

MCP_TRANSPORT=stdio

http — for remote access:

MCP_TRANSPORT=http
MCP_HTTP_PORT=8765
claude mcp add xlmcp --transport http http://your-server:8765

Security

• Path validation: only allows access to configured directories
• Token authentication: uses Jupyter API tokens
• Timeout limits: prevents runaway executions

Documentation

• Usage Guide — installation, configuration, CLI, usage examples
• Implementation — technical architecture and design details

License

MIT