ipython-kernel-mcp

An MCP server that exposes a persistent IPython kernel to Claude Code (and any MCP client). Claude can execute Python interactively, inspect variables, switch conda environments on the fly, and export the session as a Jupyter notebook.

Inspired by GPT-Auto-Data-Analytics — the tool-calling loop from that project, ported from OpenAI function-calling to the MCP standard so it works natively with Claude Code and any MCP-compatible agent.

Why

| Pain point | How this helps | |---|---| | Variables lost between tool calls | Kernel state persists for the whole session | | Plots not visible to the agent | Images returned as native MCP image content | | Hard to share results | kernel_save_notebook exports .ipynb / HTML / PDF | | Locked to one Python env | kernel_use_env('myenv') switches conda envs on the fly | | Session lost when Claude exits | Attach to a running JupyterLab kernel for persistence |

How it works

Claude Code
  └── MCP client
        └── ipython-kernel-mcp (this server)
              ├── mode: in-process  →  IPython InteractiveShell (default, fresh each session)
              └── mode: attached    →  Jupyter kernel via jupyter_client
                    ├── kernel_use_env('myenv')  →  launches kernel in any conda env
                    └── kernel_attach(id)         →  connects to running JupyterLab kernel

Tools

| Tool | Description | |------|-------------| | kernel_exec(code) | Run Python — stdout, rich text, and plots returned as images | | kernel_inspect(var_name) | repr() of any variable in the kernel namespace | | kernel_list_vars() | Show all user-defined variables and their types | | kernel_status() | Current mode, active env, and execution count | | kernel_restart() | Clear all variables and history | | kernel_add_markdown(text) | Insert a markdown cell into the exported notebook | | kernel_save_notebook(path, save_html, save_pdf) | Export session as .ipynb | | kernel_list_envs() | List all conda/mamba environments on this machine | | kernel_use_env(env_name) | Start a kernel in a named conda env and auto-attach | | kernel_list_running() | List running Jupyter kernels (for JupyterLab attach) | | kernel_attach(kernel_id) | Attach to an existing running Jupyter kernel | | kernel_detach() | Disconnect and return to in-process mode |

Installation

git clone https://github.com/Animadversio/ipython-kernel-mcp.git
cd ipython-kernel-mcp
pip install -e .

To install inside a specific conda environment (recommended — the server then runs in that env by default):

conda activate myenv
pip install -e /path/to/ipython-kernel-mcp

Connecting to Claude Code

Quickest way — use the claude CLI to register globally (user scope = all projects):

claude mcp add --scope user ipython-kernel /path/to/env/bin/ipython-kernel-mcp

Manual config — add to ~/.claude.json or a project .mcp.json:

{
  "mcpServers": {
    "ipython-kernel": {
      "command": "/path/to/your/env/bin/ipython-kernel-mcp"
    }
  }
}

Restart Claude Code. Tools appear as mcp__ipython-kernel__kernel_exec etc.

Using a specific conda environment as the default

Install the package into that env and point the MCP command at its binary:

# Install into your preferred env
conda activate torch
pip install -e /path/to/ipython-kernel-mcp

# Register
claude mcp add --scope user ipython-kernel \
  ~/miniforge3/envs/torch/bin/ipython-kernel-mcp

The server (and the in-process kernel) then run entirely inside that environment.

Switching envs without restarting Claude Code

Once registered, the agent can switch environments mid-session using kernel_use_env:

User:   analyze this dataset — it needs torch and sklearn
Claude: [calls kernel_list_envs()]        → sees: base, torch, ml-env
Claude: [calls kernel_use_env('torch')]   → starts kernel in torch env
Claude: [calls kernel_exec('import torch; print(torch.__version__)')]  → 2.x.x
Claude: [calls kernel_exec('..analysis code..')]
Claude: [calls kernel_save_notebook('results.ipynb')]

The target env needs ipykernel installed (conda install ipykernel).

Attach to a running JupyterLab kernel

This lets kernel state persist across Claude Code sessions:

1. Start JupyterLab in your env and run some cells to set up your data
2. In Claude Code: kernel_list_running() → see the kernel ID
3. kernel_attach('<kernel_id>') → Claude now operates in your live kernel
4. Close and reopen Claude Code — re-attach to pick up where you left off

Example session

You:    Load ~/data/experiment.csv and give me a statistical summary with plots

Claude: [kernel_exec] import pandas as pd; df = pd.read_csv('~/data/experiment.csv')
Claude: [kernel_exec] df.describe()                    → table output
Claude: [kernel_exec] df.hist(figsize=(12,8))          → 📊 image returned
Claude: [kernel_add_markdown] "## Distribution Analysis"
Claude: [kernel_exec] df.corr()                        → correlation matrix
Claude: [kernel_save_notebook] 'experiment_analysis.ipynb', save_html=True
→ opens in browser, all code + outputs + plots included

Requirements

• Python ≥ 3.10
• mcp[cli] ≥ 1.0, ipython ≥ 8.0, nbformat, nbconvert, pillow
• Target conda envs need ipykernel for kernel_use_env

Supported platforms

Tested on macOS. Should work on Linux. Windows support untested (paths use /).

Inspiration & lineage

This project is inspired by and ported from GPT-Auto-Data-Analytics.

That project built a local code-interpreter loop using OpenAI function-calling: an LLM agent writes Python, executes it in a live IPython kernel, reads the output, and iterates — with vision API support for interpreting generated plots.

This repo takes the same core idea and ports it to the MCP (Model Context Protocol) standard so it works natively with Claude Code and any MCP-compatible agent, without a custom tool loop. Claude's own agent loop handles the iteration; the kernel is just exposed as tools.