XLMCP is a Model Context Protocol server enabling AI assistants to interact with Jupyter notebooks, manage kernels, execute code, search knowledge bases, and track projects.
Jupyter Notebook Operations
List and find notebooks within specified directories
Get notebook info (cell counts, kernel info)
Read individual cells or all cells from a notebook
Append, insert, update, or delete cells
Kernel Management
List all running kernels with state and connection info
Start new kernels (e.g., python3)
Stop, restart, or interrupt kernels by kernel ID
Code Execution
Execute arbitrary Python code in a running kernel
Connect to a notebook's kernel (reuses existing session or creates one); returns kernel ID and VS Code attach URL
Execute specific notebook cells and save outputs back to the notebook file
Knowledge Base / Semantic Search
Index directories of .md, .py, and .ipynb files for semantic search
Search with semantic similarity, tag filters, and metadata filters
List, refresh, or drop indexes; extract tags and metadata fields
Project Management
Create, list, and get detailed project info; update descriptions
Add and read timestamped log entries
Set and get machine-readable project context (next steps, blockers, working files, active research, knowledge bases)
Allows interaction with Jupyter notebooks and kernels via JupyterHub or standalone Jupyter Server, enabling code execution, cell operations, and kernel management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@XLMCP list all notebooks in my research folder"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Collection of MCP servers, agents, and extensions for quantitative development/research with Qubx.
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-serverproject) as of v0.5.0. xlmcp is now a focused Jupyter server.
Total Tools: 17 (Jupyter notebook, kernel, and execution operations)
Related MCP server: mcp-server-jupyter
# - 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)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).
pip install xlmcp
# - or using uv
uv pip install xlmcpcd ~/devs/aix
uv pip install -e .Copy env.example to .env:
cp env.example .envEdit .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,~/researchMCP Server (Optional, defaults provided):
MCP_TRANSPORT=stdio
MCP_HTTP_PORT=8765
MCP_MAX_OUTPUT_TOKENS=25000JupyterHub: Admin panel → User → New API Token
Jupyter Server: jupyter server list shows the token
For users with multiple projects and virtual environments:
# Install in system Python (not in project venvs)
pip install xlmcp
# or: /usr/bin/python -m pip install xlmcpmkdir -p ~/.aix/xlmcp
cp env.example ~/.aix/xlmcp/.env
nano ~/.aix/xlmcp/.env # Add your JUPYTER_API_TOKENxlmcp finds config in this order:
.env in the current directory (project-specific override)
~/.aix/xlmcp/.env (global default) ← Recommended
Environment variables
cd /path/to/project
source .venv/bin/activate # if using a venv
claude mcp add --transport stdio xlmcp -- /usr/bin/python -m xlmcp.serverReplace /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 - ✓ Connectedpip install xlmcp
cp env.example .env
nano .env # Add JUPYTER_API_TOKEN
claude mcp add --transport stdio xlmcp -- python -m xlmcp.serverOr 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.serverThe -- before python separates MCP options from the server command.
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> 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.ipynbstdio (default) — for local Claude Code:
MCP_TRANSPORT=stdiohttp — for remote access:
MCP_TRANSPORT=http
MCP_HTTP_PORT=8765
claude mcp add xlmcp --transport http http://your-server:8765Path validation: only allows access to configured directories
Token authentication: uses Jupyter API tokens
Timeout limits: prevents runaway executions
Usage Guide — installation, configuration, CLI, usage examples
Implementation — technical architecture and design details
MIT
Append a new cell to the end of a notebook.
Inputs: notebook_path (required), source (required), cell_type. Returns: result
Connect to a notebook's kernel (create session if needed).
This gets an existing kernel session for the notebook or creates a new one. Use the returned kernel_id for subsequent execute_code calls.
Inputs: notebook_path (required). Returns: result
Delete a cell from the notebook.
Inputs: notebook_path (required), cell_index (required). Returns: result
Execute a specific cell in a notebook.
This will:
Connect to the notebook's kernel (or create one)
Execute the cell's code
Save outputs to notebook file (visible in VS Code)
Return the execution outputs
Inputs: notebook_path (required), cell_index (required), timeout. Returns: result
Execute Python code in a running kernel.
Inputs: kernel_id (required), code (required), timeout. Returns: result
Find notebooks by filename.
Useful when you know the notebook name but not the full path.
Inputs: filename (required). Returns: result
Get information about a notebook including cell counts and kernel info.
Inputs: notebook_path (required). Returns: result
Insert a new cell at a specific position in the notebook.
Inputs: notebook_path (required), cell_index (required), source (required), cell_type. Returns: result
Interrupt a running kernel (stop current execution).
Inputs: kernel_id (required). Returns: result
List all running Jupyter kernels.
Returns: JSON with list of kernels (id, name, state, connections)
Inputs: no named parameters. Returns: result
List all Jupyter notebooks in a directory.
Inputs: directory. Returns: result
Read all cells from a notebook.
Inputs: notebook_path (required). Returns: result
Read content of a specific cell in a notebook.
Inputs: notebook_path (required), cell_index (required). Returns: result
Restart a kernel (clears all state).
Inputs: kernel_id (required). Returns: result
Start a new Jupyter kernel.
Inputs: kernel_name. Returns: result
Stop a running kernel.
Inputs: kernel_id (required). Returns: result
Update content of an existing cell.
Inputs: notebook_path (required), cell_index (required), source (required). Returns: result
Drop index and remove all cached data for a directory.
Inputs: directory (required). Returns: result
List available metadata fields for filtering with examples.
Inputs: directory. Returns: result
Extract all unique tags from indexed documents with counts.
Inputs: directory. Returns: result
Index or update knowledge directory for semantic search.
Supports: .md (markdown), .py (Python), .ipynb (Jupyter notebooks)
Inputs: directory (required), recursive, force_reindex. Returns: result
List all indexed knowledge directories with statistics.
Returns: JSON with list of indexes (directory, collection, file_count, last_updated)
Inputs: no named parameters. Returns: result
List all registered knowledge bases from ~/.aix/knowledges.yaml.
Shows which knowledge bases are registered, whether they exist, and whether they have been indexed.
Returns: JSON with knowledge bases information including paths, descriptions, tags, existence status, and index status
Inputs: no named parameters. Returns: result
Manually force refresh of knowledge index.
Inputs: directory, recursive. Returns: result
Search knowledge base with semantic similarity and filters.
Searches across .md, .py, and .ipynb files.
Inputs: query (required), directory, tags, metadata_filters, +2 more. Returns: result
Add a log entry to project.
Log entries are automatically timestamped and appended to the project's log.md file.
Inputs: name (required), content (required), tags. Returns: result
Create a new project.
Projects are stored in ~/.aix/projects/ and contain:
description.md: Project description and metadata
log.md: Timestamped log entries
context.json: Machine-readable project state
Inputs: name (required), description, tags, project_type. Returns: result
Get detailed information about a project.
Inputs: name (required). Returns: result
Get project context.
Inputs: name (required). Returns: result
List all projects.
Returns: JSON with list of all projects including name, status, type, tags, and timestamps
Inputs: no named parameters. Returns: result
Read recent log entries from project.
Inputs: name (required), limit. Returns: result
Set or update project context.
Context is machine-readable state stored in context.json. Only provided fields are updated.
Inputs: name (required), working_files, active_research, blockers, +2 more. Returns: result
Update project description.
Inputs: name (required), description (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 33 tools
Tools are clearly grouped by domain prefixes (jupyter_, knowledge_, project_), and within each group, operations are distinct and well-described. No overlapping purposes between tools.
All tool names follow a consistent snake_case pattern with domain prefix and verb_noun structure (e.g., jupyter_execute_cell, knowledge_index_directory, project_create). No mixing of conventions.
33 tools is slightly high but justified by covering three distinct domains. Each domain has a reasonable number of tools (16, 8, 8), and all seem necessary for their purpose.
The tool surface covers core operations for Jupyter notebooks, knowledge management, and project management. Minor overlap between jupyter_connect_notebook and jupyter_start_kernel, but overall no major gaps.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
