# 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](https://github.com/gabiteodoru/ipython-mcp) by
gabiteodoru, rewritten for the [MCP Python SDK 2.x](https://py.sdk.modelcontextprotocol.io/)
(`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.

## Installation

```bash
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

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

### 2. Register with your MCP client

For Vibe CLI:

```bash
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:

```json
{
  "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

| Tool | Description |
|---|---|
| `connect_to_kernel` | Connect to a running IPython kernel via connection file |
| `execute_code` | Execute Python code in the persistent kernel |
| `kernel_status` | Check connection status |
| `interrupt_kernel` | Interrupt a running execution |

## 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](LICENSE).