ipython-kernel-mcp

An MCP (Model Context Protocol) server that connects to an existing IPython kernel, providing persistent code execution with shared state across calls.

Based on ipython-mcp by gabiteodoru, rewritten for the MCP Python SDK 2.x (MCPServer instead of the removed FastMCP).

How it works

The server connects to a running IPython kernel via a Jupyter connection file (ZMQ). Variables, imports, and computed results persist between tool calls. Multiple clients can share the same kernel — for example, VS Code's variable explorer and an AI agent connected via MCP.

Related MCP server: notebook-agent-mcp

Installation

pip install git+https://github.com/asanchezleache/ipython-kernel-mcp.git

Requires mcp>=2 and jupyter-client>=8 (installed automatically).

Usage

1. Start an IPython kernel

ipython kernel --ConnectionFileMixin.connection_file=~/ipython-mcp-connection.json

2. Register with your MCP client

For Vibe CLI:

vibe mcp add ipython-kernel --transport stdio \
  --command ipython-kernel-mcp \
  --env IPYTHON_MCP_CONNECTION=~/ipython-mcp-connection.json

For other MCP clients (Claude Desktop, etc.), add to your config:

{
  "mcpServers": {
    "ipython-kernel": {
      "command": "ipython-kernel-mcp",
      "env": {
        "IPYTHON_MCP_CONNECTION": "~/ipython-mcp-connection.json"
      }
    }
  }
}

3. Connect VS Code (optional)

Cmd+Shift+P → "Jupyter: Connect to Existing Kernel" → select the connection file. VS Code's variable explorer, inline plots, and tqdm bars share the same kernel.

Tools

Notes

• The kernel must be started separately. This server connects to an existing kernel; it does not start one.

• stdout/stderr is collected and returned when execution completes. There is no real-time streaming to the MCP client. For live output (tqdm bars, print statements), use VS Code or a terminal connected to the same kernel.

• The connection file path is resolved from the connection_file parameter, then the IPYTHON_MCP_CONNECTION environment variable.

License

MIT. See LICENSE.