内容
# 🐍 mcp-python-repl
一款**生产级别**的MCP服务器，提供具有多会话支持、沙盒、超时保护的持久化Python REPL。
为需要跨多个回合执行Python代码并具有**持久化变量**的LLM代理而构建。
## ✨ 功能
| 功能 | 描述 |
|---|---|
| **多会话** | 具有唯一ID的隔离会话 — 运行并行工作流 |
| **持久化命名空间** | 变量在会话内跨调用存活 |
| **超时保护** | 可配置的执行超时（Unix上的SIGALRM） |
| **沙盒** | 可选模式阻止危险模块（`subprocess`、`socket`等） |
| **包安装** | 即时安装pip包（优先使用`uv`以提高速度） |
| **文件执行** | 在持久化会话中运行`.py`文件 |
| **双重传输** | stdio（本地）和可流式-http（远程） |
| **完全自省** | 列出变量、获取历史记录、检查服务器状态 |
| **基于环境的配置** | 所有设置均通过`REPL_*`环境变量进行 |
## 🚀 快速开始
### 与Claude Desktop / Cursor（stdio）
在MCP配置中添加：
```json
{
"mcpServers": {
"python-repl": {
"command": "uvx",
"args": ["mcp-python-repl"]
}
}
}
```
### 使用uv（本地开发）
```bash
# 克隆并运行
git clone https://github.com/soufiane-aazizi/mcp-python-repl.git
cd mcp-python-repl
uv run mcp-python-repl
```
### HTTP传输（远程/多客户端）
```bash
REPL_TRANSPORT=streamable-http REPL_PORT=8000 uv run mcp-python-repl
```
## 🛠️ 工具
### 代码执行
| 工具 | 描述 |
|---|---|
| `repl_run_code` | 执行具有持久化命名空间的Python代码 |
| `repl_run_file` | 在会话中执行`.py`文件 |
| `repl_install_package` | 安装pip包（如果可用，则使用`uv`） |
### 命名空间管理
| 工具 | 描述 |
|---|---|
| `repl_list_namespace` | 列出会话中的所有变量 |
| `repl_get_variable` | 获取变量的完整值 |
| `repl_set_variable` | 从JSON注入变量 |
| `repl_delete_variable` | 删除特定变量 |
| `repl_clear_namespace` | 清除会话中的所有变量 |
### 会话管理
| 工具 | 描述 |
|---|---|
| `repl_list_sessions` | 列出所有活动会话 |
| `repl_delete_session` | 删除会话及其数据 |
### 调试
| 工具 | 描述 |
|---|---|
| `repl_get_history` | 获取会话的执行历史记录 |
| `repl_server_status` | 服务器配置、Python版本、会话数 |
## 🔄 持久化工作原理
```
调用1： repl_run_code(code="data = [1,2,3]; total = sum(data); result = total")
→ 返回：{"result": 6, "session_id": "a1b2c3d4e5f6", "new_variables": ["data", "total"]}
调用2： repl_run_code(code="doubled = [x*2 for x in data]; result = doubled", session_id="a1b2c3d4e5f6")
→ 返回：{"result": [2,4,6], "new_variables": ["doubled"]}
```
> **重要：** `result`变量用于向调用者返回输出。它**不**会持久化。请改用命名变量。
## ⚙️ 配置
所有设置均可通过环境变量进行配置：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `REPL_TIMEOUT` | `30` | 最大执行时间（秒） |
| `REPL_MAX_SESSIONS` | `50` | 最大并发会话数 |
| `REPL_SESSION_TTL` | `120` | 会话过期时间（分钟） |
| `REPL_MAX_OUTPUT` | `1048576` | 最大stdout/stderr捕获（字节） |
| `REPL_SANDBOX` | `false` | 启用沙盒（`true`/`false`） |
| `REPL_TRANSPORT` | `stdio` | 传输：`stdio`或`streamable-http` |
| `REPL_HOST` | `127.0.0.1` | HTTP主机（使用HTTP传输时） |
| `REPL_PORT` | `8000` | HTTP端口（使用HTTP传输时） |
| `REPL_WORKDIR` | `cwd` | 执行工作目录 |
### 沙盒模式
当`REPL_SANDBOX=true`时，以下模块被阻止：
`subprocess`、`shutil`、`ctypes`、`socket`、`http.server`、`xmlrpc`、`ftplib`、`smtplib`、`telnetlib`、`webbrowser`
并且以下内置函数被删除：`exec`、`eval`、`compile`、`__import__`（替换为受限版本）。
## 🧪 开发
```bash
# 安装开发依赖
uv sync --extra dev
# 运行测试
uv run pytest -v
# 校验
uv run ruff check src/ tests/
# 使用MCP Inspector测试
npx @modelcontextprotocol/inspector uv run mcp-python-repl
```
## 📦 项目结构
```
mcp-python-repl/
├── src/mcp_python_repl/
│ ├── __init__.py # 包元数据
│ ├── config.py # 基于环境的配置
│ ├── session.py # 具有TTL的多会话管理器
│ ├── executor.py # Python代码执行器（超时+沙盒）
│ └── server.py # 具有所有工具的MCP服务器
├── tests/
│ └── test_core.py # 单元测试+集成测试
├── pyproject.toml # uv/hatch项目配置
├── LICENSE # MIT
└── README.md
```
## 📄 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
