ipython-mcp

Let Claude Code execute code in your running IPython kernel.

You work in IPython. Claude Code works in a terminal. This tool connects the two so Claude can see your variables, run code, and inspect results without copy-paste.

┌──────────────┐                  ┌────────────────┐
│  Your IPython │    ZeroMQ       │                 │
│  Console      │◄───────────────►│  Jupyter Kernel │
│  (tmux pane)  │                 │  (background)   │
└──────────────┘                  └───────▲─────────┘
                                          │ ZeroMQ
                                          │
                                  ┌───────┴─────────┐
                                  │  MCP Server      │   stdio / JSON-RPC
                                  │  (subprocess of  │◄──────────────────── Claude Code
                                  │   Claude Code)   │
                                  └─────────────────┘

The IPython console and the MCP server are both clients of the same kernel. They share the same Python namespace. Either can create, modify, or read variables.

Prerequisites

• Claude Code
• uv
• ipykernel installed in your project's virtual environment

Install

uv tool install ipython-mcp
ipy install

ipy install registers the MCP server with Claude Code globally (user scope). Restart Claude Code after running this.

For project-level install instead (writes .mcp.json to the current directory):

ipy install --project

Usage

1. Start a kernel

In a terminal (activate your project's venv first):

cd ~/code/my-project
source .venv/bin/activate
ipy start my-project

This starts a background kernel with the name "my-project" and drops you into a Jupyter console. The kernel runs in your project's Python environment, so it has access to all your installed packages.

When you exit the console (Ctrl-D), the kernel keeps running.

2. Ask Claude to connect

In Claude Code:

You: check what columns df has
Claude: [calls connect_kernel() → lists kernels → you pick my-project]
Claude: [calls execute("df.columns.tolist()")]
Claude: The DataFrame has these columns: ['eid', 'subject', 'date', ...]

3. Manage kernels

ipy list          # show running kernels
ipy stop <name>   # stop a kernel by name
ipy stop-all      # stop all kernels

MCP tools

Four tools are exposed to Claude Code:

Tool	Description
connect_kernel()	List running kernels. Call with a kernel_id to connect.
disconnect_kernel()	Disconnect from the current kernel. The kernel keeps running.
execute(code)	Run Python code in the connected kernel. Returns stdout, stderr, expression results, and tracebacks.
get_info()	Show variables in the kernel namespace with types and short representations.

How it works

The ipy CLI manages kernel lifecycle. It starts kernels with jupyter kernel using your active environment's Python, so the kernel has access to your project's packages (pandas, numpy, etc.). Display names are stored in sidecar files alongside Jupyter's connection files.

The MCP server (ipython-mcp) is a separate process that Claude Code launches as a subprocess. It uses jupyter_client to talk to the kernel over ZeroMQ. It cannot start kernels on its own. Claude is a guest in your session.