ML Jupyter MCP - UV-Centric Persistent Jupyter Kernel for Claude

Execute Python code with persistent state across Claude conversations using MCP (Model Context Protocol).

✨ Features

🔄 Persistent State - Variables and imports persist across executions
📓 Notebook Support - Create and manage Jupyter notebooks
🐍 Virtual Environment Detection - Automatically uses project's .venv
🚀 Easy Installation - One-line setup with Claude MCP

📦 Installation

Quick Install (Recommended)

# Install from PyPI
pipx install ml-jupyter-mcp

# Add to Claude Code
claude mcp add jupyter-executor ml-jupyter-mcp

That's it! The MCP server is now available in all your Claude sessions.

Alternative: Install with UV

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

# Add to Claude Code  
claude mcp add jupyter-executor "uvx ml-jupyter-mcp"

Alternative: Clone and Install Locally

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

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

# Install in development mode
pip install -e .

# Add to Claude Code
claude mcp add jupyter-executor "$(pwd)/.venv/bin/python -m ml_jupyter_mcp.server"

🎯 Usage

Once installed, you can use these MCP tools in any Claude conversation:

Execute Python Code

# In Claude, use:
mcp__jupyter-executor__execute_code("x = 42; print(f'x = {x}')")

# Later in the same conversation:
mcp__jupyter-executor__execute_code("print(f'x is still {x}')")  # x persists!

Create Jupyter Notebooks

# Add code cells to notebooks
mcp__jupyter-executor__add_notebook_cell("analysis.ipynb", "code", "import pandas as pd")

Check Kernel Status

# Check if kernel is running
mcp__jupyter-executor__kernel_status()

Shutdown Kernel

# Clean shutdown when done
mcp__jupyter-executor__shutdown_kernel()

🛠️ How It Works

Kernel Daemon - Maintains a persistent Jupyter kernel in the background
MCP Server - Provides tools that Claude can invoke
State Persistence - All variables, imports, and definitions persist across tool calls
Auto-detection - Automatically finds and uses your project's .venv if available

📝 Example Workflow

# Start a data analysis session
mcp__jupyter-executor__execute_code("""
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

# Load your data
df = pd.read_csv('data.csv')
print(f"Loaded {len(df)} rows")
""")

# Continue analysis in next message
mcp__jupyter-executor__execute_code("""
# df is still available!
summary = df.describe()
print(summary)
""")

# Create a notebook with your analysis
mcp__jupyter-executor__add_notebook_cell("analysis.ipynb", "code", """
# Data Analysis
df.groupby('category').mean().plot(kind='bar')
plt.title('Average by Category')
plt.show()
""")

🔧 Configuration

The tool automatically:

Detects and uses .venv in your project directory
Installs required packages on first notebook creation
Manages kernel lifecycle automatically

📋 Requirements

Python 3.8+
Claude Code CLI (claude command)

🐛 Troubleshooting

MCP tools not showing up?

# Check if server is connected
claude mcp list

# Should show:
# jupyter-executor: ... - ✓ Connected

Kernel not starting?

# Remove and re-add the server
claude mcp remove jupyter-executor
claude mcp add jupyter-executor "uvx ml-jupyter-mcp"

Port 9999 already in use?

The kernel daemon uses port 9999. If it's in use, the tool will handle it automatically.

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - feel free to use in your projects!

🙏 Acknowledgments

Built for the Claude Code community to enable persistent Python execution across conversations.

Pro Tip: After installation, try asking Claude: "Use jupyter-executor to calculate fibonacci numbers and keep them in memory for later use!"