The runtimed package includes an MCP (Model Context Protocol) server that enables AI agents to interact with Jupyter notebooks programmatically.
Installation Install with the MCP extra:
pip install runtimed[mcp]
Running the Server The MCP server runs over stdio for integration with AI tools like Claude Code:
# Using the entry point runtimed-mcp
Claude Code Configuration Add to your Claude Code MCP configuration:
Installed
Development (uv)
{ "mcpServers" : { "runtimed-mcp" : { "command" : "runtimed-mcp" } } }
Session Management Tool Description connect_notebookConnect to a notebook session (by ID or path) disconnect_notebookDisconnect from the current session list_notebooksList all active notebook rooms
Kernel Management Tool Description start_kernelStart a Python or Deno kernel shutdown_kernelStop the kernel interrupt_kernelInterrupt execution get_kernel_statusGet kernel state
Cell Operations Tool Description create_cellCreate a new cell with source set_cell_sourceUpdate an existing cell’s source get_cellRead a single cell by ID get_all_cellsRead all cells in notebook delete_cellRemove a cell
Execution Tool Description execute_cellExecute a cell, return outputs run_codeCreate + execute in one call (convenience)
Available Resources URI Description notebook://cellsAll cells in current notebook notebook://statusSession and kernel status notebook://roomsActive notebook rooms
Example Usage Here’s how an AI agent might use these tools:
Connect to a notebook
connect_notebook(notebook_id="my-analysis")
Start a kernel
start_kernel(kernel_type="python", env_source="uv:prewarmed")
Run code
run_code("import pandas as pd\ndf = pd.DataFrame({'a': [1,2,3]})\ndf")
Create and execute cells
cell_id = create_cell("# Analysis\nresults = df.describe()") result = execute_cell(cell_id)
Execution Results The execute_cell and run_code tools return a result dictionary:
{ "cell_id" : "cell-abc123" , "success" : True , "execution_count" : 5 , "stdout" : "Hello, world! \n " , "stderr" : "" , "outputs" : [ { "output_type" : "stream" , "name" : "stdout" , "text" : "Hello, world! \n " }, { "output_type" : "execute_result" , "data" : { "text/plain" : "42" }, "execution_count" : 5 } ], "error" : None # or error details if execution failed }
Realtime Collaboration with nteract The MCP server connects to the same daemon as the nteract desktop app. This enables realtime collaboration:
Shared Kernel The kernel is shared between the MCP server and nteract
Live Updates Changes sync instantly via Automerge CRDT
Multi-Client Multiple MCP clients can connect with the same notebook_id
Visual Feedback Open the same notebook in nteract to see changes as the agent makes them
Environment Sources When starting a kernel, you can specify the environment source:
Source Description autoAuto-detect from notebook metadata or project files (default) uv:prewarmedFast startup from UV pool conda:prewarmedConda environment from pool uv:inlineUse notebook’s inline UV dependencies conda:inlineUse notebook’s inline conda dependencies uv:pyprojectUse pyproject.toml in notebook’s directory conda:env_ymlUse environment.yml in notebook’s directory
For Deno kernels (kernel_type="deno"), the env_source is ignored and always uses "deno".
Example Workflow Here’s a complete workflow showing an AI agent analyzing data:
# Agent connects to a new notebook connect_notebook( notebook_id = "data-analysis-2024" ) # Start Python kernel with prewarmed environment start_kernel( kernel_type = "python" , env_source = "uv:prewarmed" ) # Load data run_code( """ import pandas as pd import matplotlib.pyplot as plt df = pd.read_csv('data.csv') print(f"Loaded {len(df)} rows") """ ) # Analyze data cell_id = create_cell( """ # Summary statistics df.describe() """ ) result = execute_cell(cell_id) # Create visualization run_code( """ fig, ax = plt.subplots(figsize=(10, 6)) df.plot(kind='scatter', x='x_col', y='y_col', ax=ax) plt.title('Data Distribution') plt.show() """ ) # Clean up shutdown_kernel()
Development For development, start the dev daemon first:
Run MCP server
cd python/runtimed uv run python -m runtimed._mcp_server
Running Tests cd python/runtimed # Unit tests uv run pytest tests/test_mcp.py -v # Integration tests (requires running daemon) uv run pytest tests/test_mcp.py -v -m integration
Troubleshooting Connection Errors If the MCP server can’t connect to the daemon:
Check daemon is running: runt daemon status
Start daemon if needed: runt daemon start
Check socket path: echo $RUNTIMED_SOCKET_PATH
Kernel Not Starting If kernels fail to start:
Check daemon logs: runt daemon logs -f
Verify environment pools: runt daemon status
Try flushing pools: runt daemon flush
Outputs Not Returned If execution completes but outputs are missing:
Check if cell was actually executed: get_cell(cell_id)
Verify kernel status: get_kernel_status()
Check for errors in daemon logs
See Also