xlmcp 0.4.2

MCP server for JupyterHub/Jupyter/Qubx integration with Claude Code

AIX - AI eXtensions for quantitative development

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

XLMCP - Jupyter & Knowledge RAG MCP Server

XLMCP provides Claude Code with tools to:

• Interact with Jupyter notebooks running on JupyterHub or standalone Jupyter Server
• Search knowledge files (.md, .py, .ipynb) using semantic search with tag/metadata filtering
• Manage research/development projects with tracking, logs, and context

Total Tools: 32 (16 Jupyter + 8 Knowledge RAG + 8 Project Management)

Quick Reference

Jupyter Tools (16)

# - Notebook operations
await jupyter_list_notebooks(directory="")
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)

Knowledge RAG Tools (8)

# - Indexing
await knowledge_index_directory(directory, recursive=True, force_reindex=False)
await knowledge_refresh_index(directory=None, recursive=True)

# - Searching (directory optional - searches all KBs if not specified)
await knowledge_search(
    query,
    directory=None,        # None = search all registered KBs
    tags=None,
    metadata_filters=None,
    limit=10,
    threshold=0.5
)

# - Discovery (directory optional - aggregates from all KBs if not specified)
await knowledge_list_knowledges()              # List registered knowledge bases
await knowledge_list_indexes()                 # List indexed directories
await knowledge_get_tags(directory=None)       # None = all KBs
await knowledge_get_metadata_fields(directory=None)  # None = all KBs

# - Management
await knowledge_drop_index(directory)

Project Management Tools (8)

# - Project lifecycle
await project_create(name, description="", tags=None, project_type=None)
await project_list()
await project_get(name)
await project_update_description(name, description)

# - Logging (date-based with bullet points)
await project_add_log(name, content, tags=None)
await project_read_log(name, limit=10)

# - Context tracking (working files, next steps, blockers)
await project_set_context(
    name,
    working_files=None,
    active_research=None,
    blockers=None,
    next_steps=None,
    knowledge_bases=None
)
await project_get_context(name)

Project Structure:

~/.aix/projects/<project-name>/
├── description.md    # YAML frontmatter + description
├── log.md           # Daily logs with bullet points
└── context.json     # Machine-readable state

Installation

From PyPI (Recommended)

# - Install from PyPI
pip install xlmcp

# - Or using uv
uv pip install xlmcp

From Source

cd ~/devs/aix

# - Install dependencies
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

RAG Configuration (Optional, defaults provided):

RAG_CACHE_DIR=~/.aix/knowledge
RAG_CHUNK_SIZE=512
RAG_CHUNK_OVERLAP=100
RAG_AUTO_REFRESH=true
RAG_AUTO_REFRESH_INTERVAL=300
RAG_MAX_FILE_SIZE_MB=10
RAG_SKIP_NOTEBOOK_OUTPUTS=false

MCP Server (Optional, defaults provided):

MCP_TRANSPORT=stdio
MCP_HTTP_PORT=8765
MCP_MAX_OUTPUT_TOKENS=25000

Get 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

# Create config directory
mkdir -p ~/.aix/xlmcp

# Copy and configure .env
cp .env.example ~/.aix/xlmcp/.env
nano ~/.aix/xlmcp/.env  # Add your JUPYTER_API_TOKEN

xlmcp automatically finds config in this order:

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

3. Register with Claude Code

Per-Project Registration:

# In each project directory where you want xlmcp:
cd /path/to/project
source .venv/bin/activate  # If using venv
claude mcp add --transport stdio xlmcp -- /usr/bin/python -m xlmcp.server

Note: Replace /usr/bin/python with your system Python path. Find it with: which python (outside any venv)

Verify:

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

Benefits:

• ✅ One xlmcp installation for all projects
• ✅ Central configuration in ~/.aix/xlmcp/.env
• ✅ Connects to Jupyter kernels in any project venv
• ✅ No package conflicts between projects
• ✅ Simple registration - direct Python invocation

Simple Setup (Single Project / Quick Start)

For single project or testing:

# Install xlmcp
pip install xlmcp

# Create .env with your configuration
cp .env.example .env
nano .env  # Add JUPYTER_API_TOKEN

# Register with Claude Code (from project directory)
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

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

XLMCP CLI

The xlmcp command provides easy server management:

# - Start server
xlmcp start

# - Check status
xlmcp status

# - List all tools
xlmcp ls

# - Reindex knowledge bases
xlmcp reindex quantlib              # Reindex specific knowledge base
xlmcp reindex --all                 # Reindex all (parallel if > 1)
xlmcp reindex --all --force         # Force full reindex
xlmcp reindex --all -j 4            # Use 4 parallel jobs

# - Restart server (e.g., after adding new tools)
xlmcp restart

# - Stop server
xlmcp stop

Knowledge Base CLI Commands

The xlmcp knowledge commands let you test and verify your knowledge bases directly from the CLI:

# - List all knowledge bases with index status
xlmcp knowledge list

# - Search across all knowledge bases
xlmcp knowledge search "momentum strategy"
xlmcp knowledge search "ATR indicator" --kb library
xlmcp knowledge search "risk management" --kb library --kb backtests
xlmcp knowledge search "backtest" --limit 5 --threshold 0.6
xlmcp knowledge search "options" --tags strategy

# - Get tags from knowledge bases
xlmcp knowledge tags                    # All knowledge bases
xlmcp knowledge tags --kb library       # Specific knowledge base
xlmcp knowledge tags --kb library --kb backtests

# - Reindex knowledge bases
xlmcp knowledge reindex library         # Reindex specific KB
xlmcp knowledge reindex --all           # Reindex all KBs
xlmcp knowledge reindex --all --force   # Force full reindex

Command Options:

• --kb <name>: Specify one or more knowledge bases (can be repeated)
• --limit, -n: Maximum number of results (default: 10)
• --threshold, -t: Similarity threshold 0.0-1.0 (default: 0.5)
• --tags: Filter by tags (for search command)
• --force: Force full reindex (for reindex command)

## Usage Examples

### Jupyter Notebooks

Connect to my notebook and execute the first cell List all notebooks in research/momentum/ Execute code: print("Hello from Jupyter!")

### Knowledge Search

Claude AI can search across ALL your knowledge bases without you specifying which one:

Search my notes for "mean-reversion strategy entries" (searches all registered knowledge bases)

Find ideas tagged with #strategy about risk management (aggregates results from library, backtests, strategies, etc.)

Show me all backtests with sharpe > 1.5 (searches across all indexed directories)

Search only in backtests for "momentum factor" (you can still specify a specific KB if needed)

## After Adding New Tools

**IMPORTANT:** When new tools are added to xlmcp, you must restart the MCP server for them to be visible to MCP clients.

### Restart Methods:

**Option 1: Use xlmcp CLI** (Recommended)
```bash
xlmcp restart

Option 2: Restart Claude Code

# - Just close and reopen Claude Code

Option 3: Remove and Re-add MCP Server

claude mcp remove xlmcp -s local
claude mcp add --transport stdio xlmcp python -m xlmcp.server

Verification

# - Check server status
xlmcp status

# - List all tools
xlmcp ls

# - Should show: Total Tools: 24

Transport Modes

stdio (default) - For local Claude Code:

MCP_TRANSPORT=stdio

http - For remote access:

MCP_TRANSPORT=http
MCP_HTTP_PORT=8765

# - Then add to Claude Code
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, and usage examples
• Implementation - Technical architecture and design details

License

MIT