jupyter-kernel-mcp by codewithcheese - MCP Server

Jupyter Kernel MCP

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

Project description
Who this project is for
Project dependencies
Instructions for using Jupyter Kernel MCP
Troubleshooting
Contributing guidelines
Additional documentation
How to get help
Terms of use

Project description

With Jupyter Kernel MCP you can execute Python, TypeScript, and JavaScript code in persistent, isolated environments that maintain state between executions—perfect for AI agents performing complex data analysis and development 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-Language Support: Python, TypeScript, and JavaScript kernels
🚀 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)
🔗 Unified API: Single interface for all languages - no separate tools needed

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
Full-stack development with TypeScript/JavaScript and Python
Educational environments teaching multiple programming languages

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
Node.js (for TypeScript/JavaScript) - Required for TSLAB kernels (optional)
TSLAB - TypeScript/JavaScript kernel support (optional)

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 (Recommended)

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

Optional: Install TSLAB for TypeScript/JavaScript Support

To enable TypeScript and JavaScript kernels:

# Install TSLAB globally
npm install -g tslab
# or with pnpm
pnpm install -g tslab

# Install kernel specs
tslab install

# Verify kernels are available
jupyter kernelspec list

You should see tslab and jslab in the kernel list.

Configure with Claude Code

Add the server to Claude Code:

claude mcp add jupyter-kernel jupyter-kernel-mcp

Verify the server is listed:
```
claude mcp list
```

Configure with other MCP clients

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

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

Run Jupyter Kernel MCP

The server starts automatically when called by your MCP client

No manual startup required - the server launches when your MCP client connects.
Start your first kernel:

In Claude Code or your MCP client:
```
Please start a new Jupyter kernel for data analysis
```

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()

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 for Python, TypeScript, or JavaScript
`execute_code`	Execute code in any language kernel (auto-routes based on kernel type)
`list_kernels`	Show all active kernels with their languages
`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
TypeScript/JavaScript kernel creation fails	Install TSLAB: `npm install -g tslab && tslab install`
"tslab command not found" error	Ensure Node.js is installed and TSLAB is in PATH
TypeScript compilation errors	Check TypeScript syntax - TSLAB uses strict type checking

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 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 tom@codewithcheese.com
MCP Community - Join discussions in MCP community forums

Terms of use

Jupyter Kernel MCP is licensed under the .

Built with ❤️ for the AI agent development community

codewithcheese/jupyter-kernel-mcp