Python Repl

一个基于 Model Context Protocol (MCP) 的 Python REPL 服务器，支持多会话管理、代码执行、历史记录回放和包安装。给 AI 装上一个 Python 解释器，配合任意 Python 库即可扩展无限能力。

功能特性

• 多会话管理 - 创建、列出、重置、删除独立的 Python 执行会话
• 进程级隔离 - 每个会话运行在独立的 worker 进程中，互不干扰
• 代码执行 - 在指定会话中执行 Python 代码，自动捕获 stdout/stderr
• 文件执行 - 直接在会话中执行 Python 文件
• 表达式求值 - 自动检测最后一条语句是否为表达式并返回其值（类似 IPython）
• 超时控制 - 可设置 timeout 参数限制执行时间，超时自动终止并重启 worker
• 执行历史 - 带编号的代码块格式输出，支持 Python 切片索引
• 历史回放 - 重置运行时并从历史中重新执行代码
• 历史导出 - 将完整执行记录（代码+输出）导出到文件
• 脚本导出 - 将历史代码（仅代码）保存为 .py 文件
• 运行时重置 - 终止 worker 进程并启动新进程，保留历史记录
• 包安装 - 通过 pip 安装 Python 包
• 多通信方式 - 通过环境变量切换 stdio / SSE / Streamable HTTP 传输

安装

pip install python-repl-mcp

MCP 配置

在 .kiro/settings/mcp.json 或 ~/.kiro/settings/mcp.json 中添加：

使用 Python 启动（推荐）

直接运行在当前 Python 环境中，可以访问本机已安装的所有包。

{
  "mcpServers": {
    "python-repl": {
      "command": "python",
      "args": ["-m", "python_repl_mcp"],
      "disabled": false
    }
  }
}

使用 uvx 启动

无需预先安装，uvx 会自动下载并运行。但注意 uvx 会创建临时隔离的虚拟环境，本机已安装的库在其中不可用，需通过 install_package 工具重新安装。

{
  "mcpServers": {
    "python-repl": {
      "command": "uvx",
      "args": ["python-repl-mcp"],
      "disabled": false
    }
  }
}

环境变量

变量名	说明	可选值	默认值
MCP_TRANSPORT	MCP 通信方式	stdio, sse, streamable-http	stdio
MCP_HOST	HTTP 模式绑定地址	任意 IP 地址	127.0.0.1
MCP_PORT	HTTP 模式绑定端口	任意端口号	8000

MCP_HOST 和 MCP_PORT 仅在 MCP_TRANSPORT 为 sse 或 streamable-http 时生效。

示例：使用 SSE 模式

{
  "mcpServers": {
    "python-repl": {
      "command": "python",
      "args": ["-m", "python_repl_mcp"],
      "env": {
        "MCP_TRANSPORT": "sse",
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8080"
      },
      "disabled": false
    }
  }
}

索引规则

所有接受 start/end 参数的工具，均遵循 标准 Python 切片 约定：

• 0-based — 第一个代码块索引为 0
• 半开区间 [start, end) — start 包含，end 不包含
• 负数索引 — -1 表示最后一个，-2 表示倒数第二个
• None 默认值 — start=None 从头开始，end=None 到末尾
• 越界自动截断 — 不会报错，同 Python 切片行为

示例（假设有 5 个代码块）：

参数	效果	等价 Python
start=0, end=2	前 2 个块	lst[0:2]
start=-1	最后 1 个块	lst[-1:]
start=-2	最后 2 个块	lst[-2:]
start=1, end=-1	去掉首尾	lst[1:-1]
不传参数	全部	lst[:]

注意：输出中显示的编号 [1], [2], [3] 是 1-based 的人类可读编号，API 参数使用 0-based 索引。

工具列表

create_session

创建一个新的 Python REPL 会话。

参数	类型	必填	说明
session_id	string	否	自定义会话ID，不提供则自动生成

list_sessions

列出所有活跃的会话及其元数据（session_id、created_at、history_count、alive）。

reset_session

重置会话的命名空间和执行历史，会话本身保留。

参数	类型	必填	说明
session_id	string	是	要重置的会话ID

reset_run_context

终止当前 worker 进程并启动新进程，提供全新的 Python 解释器环境。历史记录保留。

参数	类型	必填	说明
session_id	string	是	要重置的会话ID

delete_session

永久删除一个会话及其所有数据。

参数	类型	必填	说明
session_id	string	是	要删除的会话ID

run_code

在指定会话中执行 Python 代码。支持两种模式：直接提供代码，或从历史记录中提取代码执行。

参数	类型	必填	说明
session_id	string	是	执行代码的会话ID
code	string	否	要执行的 Python 代码（不提供则从历史中提取）
start	integer	否	起始索引（Python 切片规则）
end	integer	否	结束索引（Python 切片规则）
timeout	integer	否	执行超时秒数，默认不超时

run_file

在指定会话中执行一个 Python 文件。

参数	类型	必填	说明
session_id	string	是	执行文件的会话ID
path	string	是	Python 文件路径
timeout	integer	否	执行超时秒数，默认不超时

rerun_code

重置运行时环境，从历史记录中重新执行代码。

参数	类型	必填	说明
session_id	string	是	会话ID
start	integer	否	起始索引（Python 切片规则）
end	integer	否	结束索引（Python 切片规则）
timeout	integer	否	每个代码块的超时秒数

get_history

获取会话的执行历史。

参数	类型	必填	说明
session_id	string	是	要查看的会话ID
start	integer	否	起始索引（Python 切片规则）
end	integer	否	结束索引（Python 切片规则）

输出示例：

[1] a = 1
[2] a
1
[3] b
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'b' is not defined

delete_history

删除指定范围的历史记录。

参数	类型	必填	说明
session_id	string	是	会话ID
start	integer	是	起始索引（Python 切片规则）
end	integer	否	结束索引，不传则删除 start 处的单个代码块

export_history

将执行历史（代码+输出）导出到文件。

参数	类型	必填	说明
session_id	string	是	会话ID
path	string	是	保存路径（如 'history.txt'）
start	integer	否	起始索引（Python 切片规则）
end	integer	否	结束索引（Python 切片规则）

save_script

将历史代码（仅代码，不含输出）导出为 Python 脚本文件。

参数	类型	必填	说明
session_id	string	是	会话ID
path	string	是	保存路径（如 'output.py'）
start	integer	否	起始索引（Python 切片规则）
end	integer	否	结束索引（Python 切片规则）

install_package

通过 pip 安装 Python 包到当前环境，安装后所有会话可用。

参数	类型	必填	说明
package_name	string	是	包名（如 'numpy', 'pandas==2.0.0'）

使用示例

1. create_session(session_id="demo")

2. run_code(session_id="demo", code="import math\nresult = math.sqrt(144)\nresult")
   → [1] import math
         result = math.sqrt(144)
         result
     12.0

3. run_code(session_id="demo", code="result + 1")
   → [2] result + 1
     13.0

4. run_file(session_id="demo", path="/my/project/utils.py")
   → [3] exec('utils.py')
     Loaded 5 utility functions.

5. get_history(session_id="demo")
   → [1] import math
         result = math.sqrt(144)
         result
     12.0

     [2] result + 1
     13.0

     [3] exec('utils.py')
     Loaded 5 utility functions.

6. get_history(session_id="demo", start=-1)
   → [3] exec('utils.py')
     Loaded 5 utility functions.

7. export_history(session_id="demo", path="history.txt")
   → History exported to 'history.txt'

8. save_script(session_id="demo", path="demo.py")
   → Script saved to 'demo.py'

9. reset_run_context(session_id="demo")
10. delete_session(session_id="demo")

项目结构

python-repl-mcp/
├── pyproject.toml
├── README.md
└── python_repl_mcp/
    ├── __init__.py
    ├── __main__.py
    ├── server.py      # MCP 服务器：会话管理、工具定义
    └── worker.py      # Worker 进程：代码执行引擎

开发

# 克隆项目
git clone https://github.com/miloira/python-repl-mcp.git
cd python-repl-mcp

# 开发模式安装
pip install -e .

# 运行服务器
python -m python_repl_mcp

发布

pip install build twine
python -m build
twine upload dist/*

设计理念

相比传统的固定 Skill/Tool，python-repl-mcp 的优势在于：

• 万能扩展 — pip install 任意库 + 丢一份文档 = 新能力上线
• 零开发成本 — 不需要写 tool schema，Python 能做的事它都能做
• 有状态交互 — 变量持久化，像真的在写代码一样逐步探索
• 灵活组合 — 一段代码搞定复杂编排，无需多个 tool 串联