ML Jupyter MCP

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!"

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Execute Python code with persistent state across Claude conversations using a background Jupyter kernel. Supports creating notebooks, managing virtual environments, and maintaining variables/imports between code executions.

Related MCP Servers

Optimized Memory MCP Server V2
AgentWong
-
security
A
license
-
quality
A Python-based server that implements the Model Context Protocol to interface with Claude Desktop as an MCP client, supporting interaction through efficient memory management.
Last updated -
1
MIT License
Claude Server MCP
davidteren
A
security
F
license
A
quality
Provides sophisticated context management for Claude, enabling persistent context across sessions, project-specific organization, and conversation continuity.
Last updated -
4
14
MCP Contemplation
MikeyBeez
A
security
F
license
A
quality
Provides an interface to Claude's contemplation loop, enabling continuous background cognitive processing that maintains thoughts, recognizes patterns, and develops insights between conversations.
Last updated -
9
2
MCP Project Context Server
aaronfeingold
A
security
A
license
A
quality
A persistent memory layer for Claude Code that maintains project information, technology stack, tasks, decisions, and session history between coding sessions, eliminating the need to re-explain project context.
Last updated -
9
MIT License

View all related MCP servers