jupyter-kernel-mcp 0.1.0

MCP server for stateful Jupyter kernel development with multi-kernel support

Jupyter Kernel MCP

A Model Context Protocol (MCP) server that provides stateful Jupyter kernel development with multi-kernel support for AI agents and assistants.

Table of contents

1. Project description
2. Who this project is for
3. Project dependencies
4. Instructions for using Jupyter Kernel MCP
5. Troubleshooting
6. Contributing guidelines
7. Additional documentation
8. How to get help
9. Terms of use

Project description

With Jupyter Kernel MCP you can execute Python code in persistent, isolated environments that maintain state between executions—perfect for AI agents performing complex data analysis workflows.

Jupyter Kernel MCP helps you build stateful AI agent workflows that can load datasets, perform transformations, and analyze results across multiple interactions without losing variables or computed state.

Unlike traditional stateless code execution, Jupyter Kernel MCP preserves variables, imports, and computed results between AI agent messages, enabling sophisticated multi-step data science workflows.

Key Features

• 🔄 Persistent State: Variables and imports persist between code executions
• 🚀 Multi-Kernel Support: Create and manage multiple isolated kernel environments
• 🤖 AI-Agent Ready: Seamless integration with Claude Code and other MCP clients
• 📊 Data Science Workflows: Perfect for iterative data analysis and exploration
• ⚡ Fast Communication: Direct socket-based communication with Jupyter kernels
• 🛠 Easy Management: Simple kernel lifecycle management (start, stop, reset, list)

Who this project is for

This project is intended for AI developers, data scientists, and automation engineers who want to build intelligent agents that can perform stateful data analysis and complex computational workflows.

Perfect for:

• Building AI agents that analyze datasets across multiple interactions
• Creating persistent computational environments for LLMs
• Developing stateful data science workflows with AI assistants
• Prototyping and exploring APIs with maintained context

Project dependencies

Before using Jupyter Kernel MCP, ensure you have:

• Python 3.10 or higher - Required for MCP SDK compatibility
• Claude Code, Cline, or another MCP client - To interact with the server
• Jupyter dependencies - Automatically installed with the package

Instructions for using Jupyter Kernel MCP

Get started with Jupyter Kernel MCP by installing the package and adding it to your MCP client.

Install Jupyter Kernel MCP

From PyPI (Stable Release)

1. Install using pip:

   pip install jupyter-kernel-mcp
   

   Or using uv:

   uv add jupyter-kernel-mcp
   

From GitHub (Development Version)

To install the latest development version directly from GitHub:

uv tool install git+https://github.com/codewithcheese/jupyter-kernel-mcp.git

Verify Installation

jupyter-kernel-mcp --help

Configure with Claude Code

1. Add the server to Claude Code:

   claude mcp add jupyter-kernel jupyter-kernel-mcp
   

2. Verify the server is listed:

   claude mcp list
   

Configure with other MCP clients

1. Add to your MCP client configuration (example for mcp_config.json):

   {
     "servers": {
       "jupyter-kernel": {
         "command": "jupyter-kernel-mcp"
       }
     }
   }
   

Run Jupyter Kernel MCP

1. The server starts automatically when called by your MCP client

   No manual startup required - the server launches when your MCP client connects.

2. Start your first kernel:

   In Claude Code or your MCP client:

   Please start a new Jupyter kernel for data analysis
   

3. Execute stateful code:

   Load this dataset and show me the first few rows:
   
   import pandas as pd
   df = pd.read_csv('data.csv')
   df.head()
   

4. Continue the analysis in follow-up messages:

   Now group the data by category and calculate the mean values
   

   The df variable persists from the previous execution!

Available Tools

Tool	Description
start_kernel	Create a new Jupyter kernel (with optional custom ID)
execute_python	Execute Python code in a specific kernel
list_kernels	Show all active kernels
list_variables	Display variables in a kernel's namespace
get_kernel_status	Get detailed kernel information
stop_kernel	Stop and remove a specific kernel
reset_kernel	Reset a kernel (clears all variables)

Troubleshooting

Issue	Solution
Server won't start - "No module named 'jupyter_client'"	Install dependencies: pip install jupyter-client
Kernel creation fails	Ensure Python 3.10+ is installed and accessible
MCP client can't find server	Verify installation: which jupyter-kernel-mcp
Variables not persisting between executions	Ensure you're using the same kernel_id for related executions

Other troubleshooting resources:

• Check server logs for detailed error messages
• Verify your MCP client supports the required MCP protocol version
• Ensure no firewall is blocking local kernel connections

Contributing guidelines

We welcome contributions! Please see our Contributing Guide for details on:

• How to submit bug reports and feature requests
• Development setup and testing procedures
• Code style guidelines and review process

Additional documentation

For more information:

• Model Context Protocol Specification - Official MCP documentation
• Jupyter Client Documentation - Jupyter kernel communication protocol
• Claude Code MCP Guide - Using MCP servers with Claude

How to get help

Need assistance? Here's how to get support:

• GitHub Issues - Report bugs or request features
• Email - Contact the maintainer at [e-mail]
• MCP Community - Join discussions in MCP community forums

Terms of use

Jupyter Kernel MCP is licensed under the MIT License.

---

Built with ❤️ for the AI agent development community