Python MCP Server

Python MCP 服务

用于执行 Python 代码和管理 Python 环境的 Model Context Protocol（MCP）服务。该服务允许 Claude 和其他大模型运行 Python 代码、管理文件并使用 Python 包。

功能

• 代码执行：运行 Python 代码片段或执行 Python 文件
• 文件管理：列出、读取和写入 Python 文件
• Python 环境：检查 Python 版本和环境详情
• 可配置的执行：设置超时时间、工作目录和命令行参数

先决条件

使用此 MCP 服务前，请确保已安装：

• Node.js 22 或更高版本
• Python，并且已添加到 PATH
• Claude Desktop 或 Cline

安装

1. 克隆此仓库：

git clone https://github.com/Timtech4u/python-mcp-server.git
cd python-mcp-server

2. 安装依赖：

npm ci

3. 构建项目：

npm run build

配置

Claude Desktop

1. 打开 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加 Python MCP 服务配置：

{
  "mcpServers": {
    "python": {
      "command": "node",
      "args": [
        "/absolute/path/to/python-mcp-server/dist/index.js"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code",
        "execute_python_file",
        "check_python_version",
        "list_python_files",
        "read_python_file",
        "write_python_file"
      ]
    }
  }
}

3. 将 /absolute/path/to/python-mcp-server 替换为克隆仓库的实际路径。

4. 重启 Claude Desktop。

Cline

1. 打开 Cline MCP 设置文件：

   • macOS：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Windows：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

2. 添加 Python MCP 服务配置：

{
  "mcpServers": {
    "python": {
      "command": "node",
      "args": [
        "/absolute/path/to/python-mcp-server/dist/index.js"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code",
        "execute_python_file",
        "check_python_version",
        "list_python_files",
        "read_python_file",
        "write_python_file"
      ]
    }
  }
}

3. 将 /absolute/path/to/python-mcp-server 替换为克隆仓库的实际路径。

4. 重启 Cline 或重新加载窗口。

使用方法

配置完成后，你可以通过多种方式让 Claude 运行 Python 代码。以下是一些示例：

执行 Python 代码

Can you run this Python code for me?

import random
numbers = [random.randint(1, 100) for _ in range(10)]
print(f"Random numbers: {numbers}")
print(f"Sum: {sum(numbers)}")
print(f"Average: {sum(numbers)/len(numbers)}")

执行 Python 文件

Can you execute my Python file at /path/to/my_script.py?

列出 Python 文件

Can you list all Python files in my /path/to/project directory?

读取 Python 文件

Can you show me the contents of /path/to/my_script.py?

写入 Python 文件

Can you create a Python file at /path/to/new_script.py with the following content?

def hello_world():
    print("Hello, world!")

if __name__ == "__main__":
    hello_world()

检查 Python 版本

What version of Python do I have installed?

可用工具

execute_python_code

执行 Python 代码片段。

参数：

• code（字符串，必填）：要执行的 Python 代码
• timeout（数字，可选）：最长执行时间，单位为秒（默认值：30）
• args（字符串数组，可选）：传递给脚本的命令行参数
• workingDir（字符串，可选）：脚本执行的工作目录

execute_python_file

执行 Python 文件。

参数：

• filePath（字符串，必填）：要执行的 Python 文件路径
• timeout（数字，可选）：最长执行时间，单位为秒（默认值：30）
• args（字符串数组，可选）：传递给脚本的命令行参数
• workingDir（字符串，可选）：脚本执行的工作目录

check_python_version

返回已安装 Python 版本的信息。

list_python_files

列出目录中的 Python 文件。

参数：

• dirPath（字符串，可选）：要列出 Python 文件的目录路径（默认值：当前目录）
• recursive（布尔值，可选）：是否递归搜索（默认值：false）

read_python_file

读取 Python 文件的内容。

参数：

• filePath（字符串，必填）：要读取的 Python 文件路径

write_python_file

将内容写入 Python 文件。

参数：

• filePath（字符串，必填）：要写入的 Python 文件路径
• content（字符串，必填）：要写入文件的内容
• createDirs（布尔值，可选）：如果目录不存在则创建目录（默认值：true）

故障排除

找不到 Python

如果看到类似“未安装 Python”的错误，请确保已安装 Python，并且已将其添加到系统 PATH。

权限错误

如果读取或写入文件时遇到权限错误，请确保运行 MCP 服务的用户拥有所需权限。

超时错误

服务器执行代码的默认超时时间为 30 秒。如果代码运行时间超过该时限，将会被终止。你可以通过指定 timeout 参数来延长超时时间。

许可证

MIT

验证

使用 Node.js 22+ 和 PATH 中的 Python 3 可执行文件：

npm ci
npm test
npm audit

集成测试会启动实际的 stdio 服务器、协商 MCP 会话、检查工具发现情况、执行 Python，并在临时目录中验证文件读取、写入和列表行为。两个依赖文件中都固定了 SDK 和 UUID 的版本；UUID 软件包现在自带 TypeScript 声明。