IPython内核MCP服务器

一个连接到现有IPython内核的MCP服务器，允许Claude在与IDE共享的持久环境中执行代码。

MCP是Anthropic创建的一个开放协议，它使AI系统能够与外部工具和数据源进行交互。虽然目前由Claude（桌面和CLI）支持，但开放标准允许其他LLM在未来采用它。

特性

连接到现有的IPython内核 通过连接文件
持久状态 -Claude和IDE之间共享的变量和导入
完全支持IPython -魔术命令、丰富的显示等。
实时协作 -你在IDE中编码，Claude可以检查/调试

Windows用户：WSL建议

⚠️ 对Windows用户很重要：为了获得最佳功能，强烈建议在WSL（Linux的Windows子系统）中运行MCP服务器和IPython内核。这确保了服务器可以中断LLM可能意外生成的无限循环和失控查询。

在Windows（WSL外部）上运行MCP服务器会禁用中断功能，这对于在人工智能辅助开发会话中逃逸有问题的代码至关重要。

需求

Python 3.8+
ipython, zmq 和 mcp Python包

快速开始

对于首次使用的用户，最快的入门方法是：

启动IPython内核:

   ipython kernel

将ipython mcp添加到Claude CLI:

   claude mcp add ipython-kernel "uv run ipython_mcp/server.py"

开始使用Claude CLI:

   claude

然后连接到内核：

   > connect to my ipython kernel using connection file ~/.local/share/jupyter/runtime/kernel-12345.json

   ● ipython-kernel:connect_to_kernel (MCP)(connection_file: "~/.local/share/jupyter/runtime/kernel-12345.json")
     ⎿  ✅ Connected to IPython kernel at 127.0.0.1:5555

   > execute x = 42; print(f"x = {x}")

   ● ipython-kernel:execute_code (MCP)(code: "x = 42; print(f'x = {x}')")
     ⎿  x = 42

安装

轻量级安装（仅限Claude CLI）

直接使用uv运行（无需安装pip，启动时可能会变慢；最好先尝试一下）：

claude mcp add ipython-kernel "uv run ipython_mcp/server.py"

完整安装

pip（建议经常使用）

pip install ipython-mcp

*注意：考虑使用虚拟环境来避免依赖冲突：*

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install ipython-mcp

添加到Claude CLI

安装后：

claude mcp add ipython-kernel ipython-mcp

添加到Claude桌面

添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "ipython-kernel": {
      "command": "ipython-mcp"
    }
  }
}

对于基于紫外线的安装：

{
  "mcpServers": {
    "ipython-kernel": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ipython-mcp",
        "run",
        "ipython_mcp/server.py"
      ]
    }
  }
}

用法

启动IPython内核

选项1：使用演示连接文件（建议用于测试）

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

这使用了可预测的端口（5555-5559），使连接变得容易。

选项2：基本内核启动

ipython kernel

IPython将创建一个随机连接文件。注意输出路径：

[IPKernelApp] Connection file: /home/user/.local/share/jupyter/runtime/kernel-12345.json

选项3：从IDE

大多数支持Jupyter的IDE都会自动启动内核
在IDE设置/状态中查找内核连接信息

选项4：使用自定义连接文件

ipython kernel --ConnectionFileMixin.connection_file=my_connection.json

查找连接文件

连接文件通常位于：

# List active kernels
ls ~/.local/share/jupyter/runtime/

# Example files:
# kernel-12345.json
# kernel-67890.json

工具

start_kernel(connection_file=None) -启动新的IPython内核并自动连接
connect_to_kernel(connection_file=None) -连接到现有的IPython内核
execute_code(code) -在连接的内核上执行Python代码
kernel_status() -检查当前连接状态
disconnect_kernel() -与当前内核断开连接

连接文件解析

这些工具使用此优先级查找连接文件：

显式参数 - connection_file 参数（最高优先级）
环境变量 - IPYTHON_MCP_CONNECTION
包默认值 -内置 default_connection.json （端口5555-5559）

环境变量

IPYTHON_MCP_CONNECTION -未指定时使用的默认连接文件路径

工作流示例

最简单的方法-让MCP服务器处理一切：

# In Claude CLI, start a kernel using package defaults
> start a new ipython kernel

# The tool will:
# 1. Use built-in default_connection.json (ports 5555-5559)
# 2. Start IPython kernel in background
# 3. Auto-connect to it
# 4. Return connection details

# Now execute code
> run: import pandas as pd; df = pd.DataFrame({'a': [1,2,3]})

使用环境变量：

# Set your preferred connection file
export IPYTHON_MCP_CONNECTION=/path/to/my/connection.json

# In Claude CLI
> start a new ipython kernel
# Will use your env var connection file

手动启动内核（传统方法）：

# 1. Start kernel manually
ipython kernel

# 2. In Claude CLI, connect to the kernel  
> connect to my ipython kernel using ~/.local/share/jupyter/runtime/kernel-12345.json

# 3. Execute code
> run: import pandas as pd; df = pd.DataFrame({'a': [1,2,3]})

IDE集成

该项目的设计 Spyder IDE 由于其独特的功能：

内联图 -图形直接在IDE中显示，无需单独的窗口
灵活的代码执行 -无缝运行单个行、选择或整个文件
集成IPython控制台 -没有困扰其他IDE的复制/粘贴工件
变量浏览器 -实时检查Claude和IDE之间的共享状态

虽然其他IDE可以与此MCP服务器配合使用，但Spyder为数据科学工作流程提供了流畅的体验，您需要在同一个持久的Python环境中进行交互式编码和人工智能辅助。

安全考虑

此MCP服务器使用Jupyter的标准连接协议和HMAC-SHA256消息签名。

连接文件安全

如果你在本地使用这个 （单用户机器）：

带有演示密钥的默认连接文件(demo-key-12345)很好
仅绑定到本地主机（127.0.0.1）-无法从网络访问
使用可预测的端口和密钥简化设置和调试

但如果您需要增强安全性 （共享机器、网络访问、生产）：

# Generate a secure connection file with random key
python -c "
import json, secrets
conn = {
    'shell_port': 5555, 'iopub_port': 5556, 'stdin_port': 5557,
    'control_port': 5558, 'hb_port': 5559, 'ip': '127.0.0.1',
    'key': secrets.token_hex(32), 'transport': 'tcp',
    'signature_scheme': 'hmac-sha256', 'kernel_name': ''
}
print(json.dumps(conn, indent=2))
" > secure_connection.json

# Use your secure connection file (via env var or explicit parameter)
export IPYTHON_MCP_CONNECTION=secure_connection.json
ipython kernel --ConnectionFileMixin.connection_file=secure_connection.json

附加安全措施:

设置限制性文件权限： chmod 600 your_connection.json
使用不同的端口以避免冲突
永远不要将带有真实密钥的连接文件提交给版本控制
如果绑定到非本地主机地址，请考虑防火墙规则

WSL/Windows集成

在Windows上使用Claude CLI（在WSL中运行）时，您可能希望在Windows端运行IPython内核，同时将MCP服务器保持在WSL中。这允许您使用Windows Python环境（如Miniconda），同时仍然可以从Claude CLI访问它们。

从WSL启动Windows IPython内核：

# Using PowerShell to start kernel in background
powershell.exe -Command "Start-Process -WindowStyle Hidden cmd -ArgumentList '/c', 'C:\Users\\miniconda3\Scripts\activate.bat C:\Users\\miniconda3 && python -m ipykernel_launcher -f 
'"

哪里可以是：

您自己的连接文件： \\\\wsl.localhost\\Ubuntu\\home\\\\my_connection.json
包默认值（如果WSL上安装了pip）： \\\\wsl.localhost\\Ubuntu\\home\\\\.local\\lib\\python3.x\\site-packages\\ipython_mcp\\default_connection.json
开发版本： \\\\wsl.localhost\\Ubuntu\\home\\\\ipython-mcp\\src\\ipython_mcp\\default_connection.json

这种方法：

激活您的Windows Miniconda环境
使用共享连接文件启动IPython内核
在隐藏的背景窗口中运行
允许基于WSL的Claude CLI连接到Windows Python环境

WSL2端口通信（Windows用户）

*如果您不在Windows上，请跳过此部分。*

由于Claude CLI仅在Windows上是WSL，但您可能希望使用Windows Python环境或IDE，因此您需要在WSL2和Windows之间进行适当的端口通信。

.wslconfig文件设置

地点： C:\Users\{YourUsername}\.wslconfig

添加镜像网络配置：

# Mirrored networking mode for seamless port communication
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

重新启动WSL2

从Windows PowerShell/CMD运行（不是从WSL中运行）：

wsl --shutdown
# Wait a few seconds, then start WSL again

镜像网络提供了什么

✅ 双向直接本地主机通信
✅ 无需手动端口转发
✅ 更好的VPN兼容性
✅ 简化的网络连接（Windows和WSL2共享网络接口）
✅ 自动处理防火墙规则

测试端口通信

测试WSL2→ Windows（本地主机）：

# In WSL2, test connection to Windows IPython kernel
python -c "import zmq; ctx = zmq.Context(); sock = ctx.socket(zmq.REQ); sock.connect('tcp://127.0.0.1:5555'); print('Connection successful')"

测试窗口→ WSL2（本地主机）：

# In Windows, test connection to WSL2 service
python -c "import zmq; ctx = zmq.Context(); sock = ctx.socket(zmq.REQ); sock.connect('tcp://127.0.0.1:5555'); print('Connection successful')"

镜像网络的已知局限性

仅本地主机服务：某些服务可能未完全镜像
mDNS不起作用 在镜像模式下
一些Docker配置 可能有问题
需要Windows 11 22H2+ （建筑22621+）

建筑

此MCP服务器充当桥在Claude和现有的IPython内核之间：

克劳德 ↔ MCP服务器 ↔ IPython内核 ↔ 您的IDE
各方共享相同的持久Python环境
变量、导入和状态在所有连接中持续存在
使用标准的Jupyter消息传递协议（ZMQ）进行通信

责任界限

MCP服务器管理：

通过ZMQ套接字连接到现有内核
消息格式和协议合规性
代码执行请求和响应处理

用户管理：

内核生命周期（启动、停止、监控）
连接文件创建和安全
内核配置和环境设置

为什么要分开？

灵活性：以您喜欢的方式启动内核（CLI、IDE、Jupyter等）
持久性：内核可以超过MCP连接，并在工具之间共享
控制：您决定内核配置、环境和生命周期
简洁：MCP服务器侧重于通信，而不是流程管理

这 start_kernel 工具作为 便利助手 -不是要求。许多用户更喜欢通过IDE、Jupyter或自定义脚本启动内核。

内核中断和关闭

IPython内核中断模式

IPython内核支持两种不同的中断模式，这两种模式决定了客户端如何停止运行代码：

1.信号模式（默认）

使用操作系统信号（Unix上的SIGINT，Windows上的等效信号）
只有直接向内核进程发送信号才能中断执行
忽略通过Jupyter协议发送中断请求的IDE客户端
这就是为什么IDE中的CTRL+C通常不起作用，但内核窗口中的CTRL+C却起作用的原因

2.消息模式

用途 interrupt_request 通过控制套接字（Jupyter协议）发送消息
IDE客户端可以通过标准Jupyter协议消息中断
直接向进程发送操作系统信号可能会被忽略
必须在内核的kernelspec中配置 "interrupt_mode": "message"

实现

此MCP服务器实现了 双重方法 它适用于两种中断模式：

方法1:Jupyter协议（第一次尝试）

发送 interrupt_request 通过控制套接字发送消息
适用于配置为的内核 interrupt_mode: "message"
干净、符合协议的方法

方法2:OS信号回退

用途 psutil 将信号情报直接发送到内核进程
适用于默认内核，使用 interrupt_mode: "signal"
处理99%的标准IPython安装
局限性：信号情报功能在以下情况下禁用：

- MCP服务器在Windows上运行（WSL之外） - MCP服务器和IPython内核在WSL/Windows划分的两侧运行

中断工具首先尝试控制套接字方法，然后在需要时回退到直接SIGINT。

可用工具

interrupt_kernel() -使用双方法停止当前运行的代码
shutdown_kernel() -通过Jupyter协议优雅地关闭内核，并强制终止回退

这种方法确保了跨不同配置和平台的可靠内核管理，而不需要用户修改其内核设置。

已知限制

内核中断（SIGINT）限制

Windows平台：MCP服务器在Windows上运行时（WSL之外）禁用内核中断
跨平台设置：当MCP服务器和IPython内核在WSL/Windows划分的相对侧运行时，禁用内核中断
影响：在这些配置中，LLM无法自动逃脱无限循环或取消失控代码

Ipython MCP

快速接入

详细介绍