ML Jupyter

Provides a persistent Python execution environment with notebook support and automatic venv detection for Claude conversations.

python

1

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mayank-ketkar-sf-claudejupy": {
      "command": "$(pwd)/.venv/bin/python",
      "args": [
        "-m",
        "ml_jupyter_mcp.server"
      ]
    }
  }
}

You can run Python code inside Claude conversations with a persistent state across messages using a dedicated MCP server. It keeps variables and imports available, supports notebooks, and automatically uses your project’s virtual environment when present, so you can iterate interactively without losing context.

How to use

Install and register the Jupyter MCP server in Claude to enable persistent Python execution across your conversations. Once registered, you can execute code that remains in memory across messages, create and manage notebooks, and let the server auto-detect your project’s virtual environment for consistent dependency management.

Key usage patterns you will perform in Claude:

Run a code snippet to establish and reuse variables and imports across messages.
Add code cells to a notebook so you can organize long analyses across messages.
Check if the kernel is running to confirm the persistent session is active.
Shut down the kernel when you’re finished to clean up resources.

How to install

# Prerequisites
- Python 3.8+
- Claude Code CLI installed and configured (the `claude` command)
- Optional: a project with a virtual environment (recommended)

# Quick install (recommended)
pipx install ml-jupyter-mcp

# Register with Claude Code
claude mcp add jupyter-executor ml-jupyter-mcp

If you prefer using the UV tool for installation, you can install via UV and then register the MCP in Claude Code.

# Install with UV tool
uv tool install ml-jupyter-mcp

# Register with Claude Code
claude mcp add jupyter-executor "uvx ml-jupyter-mcp"

If you want to run the server locally in development mode, clone the project, set up a virtual environment, and install in editable mode. Then register the CLI entry point for Claude.

# Clone the repository
git clone https://github.com/mayankketkar/ml-jupyter-mcp.git
cd ml-jupyter-mcp

# Create and activate a virtual environment
uv venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Register the MCP endpoint that Claude should invoke
claude mcp add jupyter-executor "$(pwd)/.venv/bin/python -m ml_jupyter_mcp.server"

Additional notes

The server is designed to automatically detect and use your project’s virtual environment if present. It also handles kernel lifecycle automatically, so you don’t need to manage the Jupyter process directly.

Configuration and troubleshooting

There are a few tips to keep in mind when using this MCP server.

If the MCP tools don’t appear in Claude, re-add the executor or ensure the registration command was completed successfully.
If the kernel fails to start due to port conflicts or other issues, Claude will typically handle restarts automatically. If needed, re-run the standard installation and registration steps above.

Available tools

execute_code

Execute Python code in the persistent kernel, with all previously defined variables and imports available in subsequent tool calls.

add_notebook_cell

Add a new cell to a Jupyter notebook managed by the server, allowing you to build notebooks incrementally across conversations.

kernel_status

Check whether the persistent kernel is currently running and ready to execute code.

shutdown_kernel

Shut down the persistent kernel when you are done to release resources.