MCP Python Toolbox

MCP Python Toolbox

一个本地 Model Context Protocol（stdio）服务，可向 Claude Desktop 等 MCP 客户端提供 Python 工作区工具：读写文件、分析/格式化/检查 Python、管理项目 .venv，以及运行代码。

该项目未发布到 PyPI，也不会对代码执行进行沙箱隔离。请参阅安全。

概述

针对某个工作区目录启动服务。连接的 MCP 客户端随后可以：

• 在该工作区内读取、写入和删除文件，以及列出目录
• 分析、格式化和检查 Python 代码
• 创建虚拟环境并安装依赖项
• 在主机上执行 Python 代码片段

功能

文件操作（FileOperations）

• 文件工具仅限于某个工作区目录
• 解析路径，并拒绝任何超出工作区根目录的路径
• 通过针对行的操作读取和写入文件（write_file 会创建父目录）
• 删除文件（delete_file 不会删除目录）
• 列出目录内容及其元数据（大小、类型、修改时间）
• 类中有 create_directory，但未将其注册为 MCP 工具

代码分析（CodeAnalyzer）

• 使用 AST 解析和分析 Python 代码结构
• 提取详细信息，包括：
  • 导入语句及其别名
  • 带参数和装饰器的函数定义
  • 带基类和方法的类定义
  • 全局变量赋值
• 使用以下工具格式化代码：
  • Black（默认）
  • PEP8（使用 autopep8）
• 使用 Pylint 检查代码（JSON 输出，子进程超时为 30s）

项目管理（ProjectManager）

• 创建工作区 .venv（venv.create，包含 pip）
• 通过 pip 将依赖项安装到该 .venv 中：
  • 从 requirements.txt 安装
  • 从 pyproject.toml 的 [project.dependencies] 安装
• 类中的 update_package / create_requirements_file 使用 .venv 解释器（执行 pip install --upgrade / pip freeze）
• list_packages 和 check_conflicts 检查的是运行中服务的解释器可见的包（importlib.metadata），而不是工作区 .venv 中的包

代码执行（CodeExecutor）

• 将代码片段写入临时文件，并使用 subprocess 运行
• 如果工作区 .venv 的 Python 解释器存在，则使用该解释器
• 捕获 stdout、stderr 和退出代码
• 可选工作目录；使用与 FileOperations 相同的解析并拒绝越界路径检查（默认：工作区根目录；拒绝符号链接越界）
• 超时时间可配置（默认 30s，最长 300s）；超时后会终止进程组，并返回已有的 stdout/stderr
• 仍未进行沙箱隔离：使用相同的用户权限，可访问文件系统和网络，除超时时间外没有资源限制

安全性

这里没有沙箱。服务及其所有工具都以启动它的进程所使用的同一操作系统用户和权限运行。这里没有容器、seccomp 过滤器、导入允许列表或网络限制。仅将其用于你信任的 MCP 客户端和工作区。

代码实际实施的限制：

• read_file、write_file、delete_file 和 list_directory 会解析路径，并拒绝访问工作区根目录之外的路径。分析、lint 和格式化操作不会使用此检查。
• execute_python 仍会在宿主机上无沙箱地执行：创建临时 .py 文件，并通过工作区的 .venv 解释器启动子进程。代码片段可以读取或写入该用户有权访问的任何位置、启动进程并使用网络。只有以下两项保护措施：
  • 超时（默认 30 秒；可通过 --execute-timeout、MCP_PYTHON_EXECUTE_TIMEOUT 环境变量或每次调用的 timeout 参数设置，最长 300 秒）。超时后会终止整个进程组，并在结构化错误中返回任何已生成的部分 stdout/stderr。
  • working_dir 会使用与 FileOperations 相同的工作区检查进行解析。解析到工作区之外的路径（包括通过符号链接逃逸的路径）都会被拒绝。默认值为工作区根目录。
• 没有其他资源限制（CPU、内存、打开的文件或网络）。
• create_venv 和 install_dependencies 可以创建 .venv，并使用 pip 将软件包安装到其中。

请勿向不可信的客户端公开此服务，也不要将 --workspace 指向你不愿让助手修改或执行其中代码的目录树。

安装

1. 克隆代码仓库：

git clone https://github.com/gianlucamazza/mcp_python_toolbox.git
cd mcp_python_toolbox

2. 创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

3. 以开发模式安装软件包：

pip install -e ".[dev]"

使用方法

作为 CLI 工具运行

启动服务最简单的方法是使用 CLI：

# Start with current directory as workspace
python -m mcp_python_toolbox

# Or specify a workspace directory
python -m mcp_python_toolbox --workspace /path/to/your/project

# Optional: default execute_python timeout in seconds (default 30, max 300)
python -m mcp_python_toolbox --execute-timeout 30
# or: export MCP_PYTHON_EXECUTE_TIMEOUT=30

在 Claude Desktop 中设置

Claude Desktop 可以自动启动和管理 MCP Python Toolbox 服务。配置方法如下：

1. 按照上文所述安装并设置 MCP Python Toolbox
2. 在 Claude Desktop 的 MCP 工具配置中，为 Python Toolbox 添加配置项：

"python-toolbox": {
  "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python",
  "args": [
    "-m",
    "mcp_python_toolbox",
    "--workspace",
    "/Users/username/path/to/workspace"
  ],
  "env": {
    "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
    "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
    "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv",
    "PYTHONHOME": ""
  }
}

3. 根据你的环境自定义路径
4. Claude Desktop 会在需要时自动启动 MCP 服务
5. 现在，Claude 可以通过 MCP 接口使用 Python 开发工具

以编程方式使用

from mcp_python_toolbox import PythonToolboxServer

server = PythonToolboxServer(workspace_root="/path/to/your/project")
server.setup()
server.run()

核心模块示例

文件操作

from mcp_python_toolbox.core import FileOperations

file_ops = FileOperations(workspace_root="/path/to/project")

# Read file contents
content = file_ops.read_file("src/example.py")
# Read specific lines
lines = file_ops.read_file("src/example.py", start_line=10, end_line=20)

# Write to file
file_ops.write_file("output.txt", "Hello, World!")
# Append to file
file_ops.write_file("log.txt", "New entry\n", mode='a')

# List directory contents
contents = file_ops.list_directory("src")
for item in contents:
    print(f"{item['name']} - {item['type']} - {item['size']} bytes")

代码分析

from mcp_python_toolbox.core import CodeAnalyzer

analyzer = CodeAnalyzer(workspace_root="/path/to/project")

# Analyze Python file structure
analysis = analyzer.parse_python_file("src/example.py")
print(f"Found {len(analysis['functions'])} functions")
print(f"Found {len(analysis['classes'])} classes")

# Format code
formatted = analyzer.format_code(code, style='black')

# Lint code
issues = analyzer.lint_code("src/example.py")
for issue in issues:
    print(f"Line {issue['line']}: {issue['message']}")

项目管理

from mcp_python_toolbox.core import ProjectManager

pm = ProjectManager(workspace_root="/path/to/project")

# Create virtual environment
pm.create_virtual_environment()

# Install dependencies
pm.install_dependencies()  # from requirements.txt or pyproject.toml
pm.install_dependencies("requirements-dev.txt")  # from specific file

# Check for conflicts
conflicts = pm.check_dependency_conflicts()
if conflicts:
    print("Found dependency conflicts:")
    for conflict in conflicts:
        print(f"{conflict['package']} requires {conflict['requires']}")

# Update packages
pm.update_package("requests")  # to latest
pm.update_package("flask", version="2.0.0")  # to specific version

代码执行

from mcp_python_toolbox.core.code_executor import CodeExecutor

executor = CodeExecutor(workspace_root="/path/to/project")

code = '''
def greet(name):
    return f"Hello, {name}!"

print(greet("World"))
'''

result = executor.execute_code(code)
print(f"Output: {result['stdout']}")
print(f"Errors: {result['stderr']}")
print(f"Exit code: {result['exit_code']}")

开发

测试

pytest

类型检查

mypy src/mcp_python_toolbox

Lint

pylint src/mcp_python_toolbox

格式化

black src/mcp_python_toolbox

贡献

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• MCP 服务使用 Python SDK（FastMCP）构建
• 使用 Black 进行格式化；使用 Pylint 进行 lint（在子进程中运行）