Skip to main content
Glama
miloira

python-repl-mcp

by miloira
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

python-repl-mcp

一个基于 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 传输

Related MCP server: MCP Code Mode

安装

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 串联

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Code Mode

    anaseqal
    A
    license
    A
    quality
    D
    maintenance
    Universal Python code execution MCP server that lets LLMs write and run Python for any task, with auto-install packages, streaming output, and automatic file display.
    9
    1
    MIT

  • Code Box

    MadhanMohanReddy2301
    A
    license
    Not graded
    quality
    C
    maintenance
    A self-hosted MCP server providing stateful code execution (Python/JavaScript) with SQL query support, file I/O, and artifact management, replacing Azure Code Interpreter.
    MIT

  • mcp-python-repl

    aazizisoufiane
    A
    license
    A
    quality
    D
    maintenance
    A production-grade MCP server providing a persistent Python REPL with multi-session support, sandboxing, and timeout protection, enabling LLM agents to execute Python code across multiple turns with variables that persist between calls.
    12
    1
    MIT