AI导哈

Jupyter内核MCP服务器

一个通过Jupyter内核为AI助手提供有状态、持久化工作空间的模型上下文协议（MCP）服务器。

  • by democratize-technology
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 democratize-technology/jupyter-kernel-mcp

使用说明

Jupyter内核MCP服务器

一个模型上下文协议（MCP）服务器，通过Jupyter内核为AI助手提供有状态、持久的工作空间。

这是什么？

此MCP服务器使AI助手（如Claude）能够在持久的Jupyter内核会话中执行代码。与每次重新开始的传统代码执行不同，这会在对话中保持状态——变量、导入的库和正在运行的进程在消息之间持续存在。

主要特点

  • 持久状态：变量和导入在消息中仍然可用
  • 多语言支持：Python、R、Julia、Go、Rust、TypeScript等
  • 笔记本管理：创建、编辑和管理Jupyter笔记本
  • 实时执行：代码运行时的流输出
  • 搜索功能：在所有笔记本中查找代码
  • 自动重新连接：WebSocket连接以指数回退重试
  • AI友好发现：针对下一步行动的情境感知建议

用例

  • 数据分析：一次性加载大型数据集，跨多个对话进行分析
  • 发展：逐步构建和测试代码，并完全保留状态
  • 教育：循序渐进的教程，每一步都建立在上一步的基础上
  • 研究：跨越多个会话的长期实验

设置

1.克隆存储库

git clone <your-repository-url>
cd jupyter-kernel-mcp

2.安装依赖项

此项目使用 uv 用于依赖性管理。如果你没有 uv 安装：

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

3.配置环境

服务器需要配置才能连接到Jupyter实例。复制示例配置文件：

cp .env.example .env

然后编辑 .env 根据您的具体设置：

# For Jupyter server
JUPYTER_HOST=localhost
JUPYTER_PORT=8888
JUPYTER_TOKEN=your-jupyter-token-here

4.查找您的Jupyter令牌

如果你在本地运行Jupyter：

jupyter server list

这将显示如下输出：

http://localhost:8888/?token=abc123... :: /path/to/notebooks

复制令牌值并将其添加到您的 .env 文件。

配置选项

Jupyter服务器设置

  • JUPYTER_HOST -Jupyter服务器的主机名或IP地址（默认值： localhost)
  • JUPYTER_PORT -Jupyter服务器正在监听的端口（默认： 8888)
  • JUPYTER_PROTOCOL -HTTP连接协议： http 或 https （默认值： http)
  • JUPYTER_WS_PROTOCOL -WebSocket连接协议： ws 或 wss （默认值： ws)
  • JUPYTER_TOKEN -Jupyter的身份验证令牌（必需）

示例配置

本地Jupyter服务器

JUPYTER_HOST=localhost
JUPYTER_PORT=8888
JUPYTER_PROTOCOL=http
JUPYTER_WS_PROTOCOL=ws
JUPYTER_TOKEN=your-token-here

使用HTTPS的远程Jupyter服务器

JUPYTER_HOST=jupyter.example.com
JUPYTER_PORT=443
JUPYTER_PROTOCOL=https
JUPYTER_WS_PROTOCOL=wss
JUPYTER_TOKEN=your-secure-token

运行服务器

先决条件

  1. Jupyter服务器：你需要一个正在运行的Jupyter服务器。如果你没有：

    # Install Jupyter
pip install jupyter

# Start Jupyter (in a separate terminal)
jupyter notebook --no-browser

  2. 环境配置：确保您已创建并配置了 .env 文件（请参阅上面的“设置”部分）

启动MCP服务器

Jupyter运行并配置后：

./run_server.sh

或者直接使用Python：

uv run python jupyter_kernel_mcp.py

服务器将尝试使用您的Jupyter实例中的配置进行连接 .env 文件。

MCP客户端配置

要将此服务器与MCP客户端（如Claude Desktop）一起使用，请将以下内容添加到MCP设置中：

{
  "jupyter-kernel": {
    "command": "/path/to/jupyter-kernel-mcp/run_server.sh"
  }
}

替换 /path/to/jupyter-kernel-mcp 使用克隆此存储库的实际路径。

可用工具

服务器为AI助手提供了多种工具：

核心执行工具

  • compute() -智能执行，自动检测流媒体需求
  • q() -快速计算，计算简单
  • execute() -完全控制执行，结果详细
  • stream_execute() -带有时间戳的实时流式输出

发现和状态管理

  • suggest_next() -基于当前内核状态的上下文感知建议
  • vars() -查看内存中的变量
  • workspace() -所有内核和笔记本的鸟瞰图
  • kernel_state() -详细的内存使用状态检查

笔记本操作

  • notebook() -自然语言笔记本操作（创建、添加、读取等）
  • create_notebook() -创建新笔记本
  • add_to_notebook() -向现有笔记本添加代码
  • search_notebooks() -搜索所有笔记本

系统管理

  • list_available_kernels() -查看支持的语言
  • reset() -清除内核状态（谨慎使用！）

新功能

自动重新连接

服务器现在包括具有指数回退的自动WebSocket重新连接。如果连接失败，它将：

  1. 随着延迟的增加（1秒、2秒、4秒、8秒，最多30秒）重试
  2. 重试时显示鼓励消息
  3. 优雅地处理瞬态网络问题

情境感知建议

新的 suggest_next() 该工具根据您的当前状态提供智能建议：

# After loading a DataFrame
>>> suggest_next()
🔮 Based on your current state:

📊 You have a DataFrame 'df' loaded (1000×5)
You might want to:
  • df.describe() - Get statistical summary
  • df.info() - Check data types and memory usage
  • df.head(10) - View first 10 rows
  • df.isnull().sum() - Check for missing values

故障排除

连接被拒绝

如果您遇到连接错误：

  • 验证Jupyter是否正在运行： jupyter server list
  • 检查你的 JUPYTER_HOST 和 JUPYTER_PORT 设置
  • 确保防火墙允许连接到Jupyter端口

认证失败

如果您遇到身份验证错误：

  • 验证您的 JUPYTER_TOKEN 是正确的
  • 尝试通过重新启动Jupyter来重新生成令牌
  • 检查令牌是否完全匹配（没有额外空格）

相关 MCP