内容
PyMOL-MCP：使用 Claude 或 OpenAI Codex 控制 PyMOL
PyMOL-MCP 通过模型上下文协议（MCP）将 PyMOL 连接到 AI 客户端，使 Claude 和 OpenAI Codex 能够直接与 PyMOL 交互并控制它。它支持通过自然语言进行对话式结构生物学、分子可视化和分析。
## 功能特点
- **双向通信**：通过 MCP 服务器将 Claude 或 Codex 连接到 PyMOL
- **智能命令解析**：对 PyMOL 命令进行自然语言处理
- **分子可视化控制**：操纵表示、颜色和视图
- **结构分析**：执行测量、比对和其他分析
- **无任意代码执行**：仅允许列出的 `cmd.*` 调用被调度，无 `exec()` 或 `eval()`
## 先决条件
- 在您的系统上安装 PyMOL
- Claude Desktop、Claude Code 或 OpenAI Codex
- Git
- 如果您想使用[快速入门](#快速入门)，则需要 Make
## 快速入门
对于 Claude Code，安装 [uv](#步骤-1-安装-uv-包管理器) 、 *PyMOL* 和 *Make*：
```bash
git clone https://github.com/jonathan6620/pymol-mcp
cd pymol-mcp
uv sync
claude mcp add pymol -s user -- uv --directory $(pwd) run pymol-mcp
make install
```
对于 OpenAI Codex，请将 `claude mcp add` 命令替换为：
```bash
codex mcp add pymol -- uv --directory "$(pwd)" run pymol-mcp
```
重启 PyMOL 并启动一个新的 Claude Code 会话。启动时，PyMOL 会打印 `MCP socket plugin auto-started on port 9876`，或下一个空闲端口。
如果 `make` 找不到 PyMOL 可执行文件，则传递路径：`make install PYMOL=/full/path/to/pymol`。
对于 Claude Desktop，请使用[步骤 3，选项 A](#选项-a-claude-desktop) 代替 `claude mcp add` 行，然后运行 `make install`。
## 完整安装指南
### 步骤 1：安装 uv 包管理器
**在 macOS/Linux 上：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
或在 macOS 上使用 Homebrew：
```bash
brew install uv
```
**在 Windows 上：**
```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
set Path=C:\Users\[YourUsername]\.local\bin;%Path%
```
对于其他平台，请访问 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation/)。
### 步骤 2：克隆仓库
```bash
git clone https://github.com/jonathan6620/pymol-mcp
cd pymol-mcp
uv sync
```
### 步骤 3：配置您的 MCP 客户端
使用 Claude Desktop、Claude Code 或 OpenAI Codex。
#### 选项 A：Claude Desktop
1. 打开 Claude Desktop
2. 进入 Claude > 设置 > 开发者 > 编辑配置
3. 这将打开 `claude_desktop_config.json` 文件
4. 添加 MCP 服务器配置：
```json
{
"mcpServers": {
pymol": {
"command": "[uv 的完整路径]",
"args": [
"--directory",
"[克隆的 pymol-mcp 仓库的完整路径]",
"run",
"pymol-mcp"
]
}
}
}
```
```json
{
"mcpServers": {
"pymol": {
"command": "/Users/username/.local/bin/uv",
"args": [
"--directory",
"/Users/username/pymol-mcp",
"run",
"pymol-mcp"
]
}
}
}
```
> **注意：** 确保您为系统指定完整的路径。在 macOS/Linux 上运行 `which uv` 或在 Windows 上运行 `where uv`（Windows）以查找 uv 二进制文件，因为 Claude Desktop 不会继承您的 shell 的 `PATH`。 上，请使用正斜杠（/）而不是反斜杠。
#### 选项 B：Claude Code（CLI）
从克隆的仓库目录 `claude` CLI 添加 PyMOL MCP 服务器：
```bash
claude mcp add pymol - -- uv --directory $(pwd) run pymol-mcp
```
`$(pwd)` 扩展到您所在的仓库，因此请从 `pymol-mcp` 目录运行此命令。 从其他任何地方，请传递完整路径：
```bash
claude mcp add pymol -s user -- uv --directory /path/to/pymol-mcp run pymol-mcp
```
这会将配置保存到 `~/.claude.json`。您可以通过以下方式验证是否已添加：
```bash
claude mcp list
```
> **注意：** 添加 MCP 服务器后，您必须重启 Claude Code 会话才能使工具可用。
#### 选项 C：OpenAI Codex
从克隆的仓库目录中，注册本地 stdio MCP 服务器：
```bash
codex mcp add pymol -- uv --directory "$(pwd)" run pymol-mcp
```
通过 `codex mcp list` 验证配置。Codex 在 `~/.codex/config.toml` 中 配置；Codex CLI、IDE 扩展和 ChatGPT 桌面应用程序在同一 Codex 主机上共享它。添加服务器重启客户端。
等效配置是：
```toml
[mcp_serversol]
command = "uv"
args = ["--directory", "/full/path/to/pymol-mcp", "run", "pymol-mcp"]
```
### 步骤 4：安装 PyMOL 套接字插件
MCP 服务器通过套接字与 PyMOL 通信。每个 PyMOL 都声称其在 9876-9895 的范围内，因此可以同时运行多个实例。从您在步骤 2 中克隆的安装套接字监听器插件：
```bash
pymol -/install_plugin.py
```
重启 PyMOL 以使其加载新的插件。
### 5：启动 PyMOL 套接字监听器
在 Claude 可以向 Py 发送命令之前，必须激活套接字监听器。运行此命令以配置 PyMOL 在应用程序打开时启动插件。
```bash
make install-pymolrc
```
如果未安装 `make`，请创建或编辑 `~/.pymolrc.py`。
```python
import importlib, threading, time
# PyMOL 从其启动插件，名称为此名称，因此无需配置路径 -
# 它在每台机器和MOL 发行版上都相同。需要安装插件（步骤 4）。
PLUGIN_MODULE = "pmg_tk.startup.pymol-mcp-socket-plugin"
def _auto_start_mcp_socket():
time.sleep(3) # 让 PyMOL 的插件初始化
try:
plugin = importlib.import_module(PLUGIN_MODULE)
except ImportError:
print("MCP 套接字插件未安装 -- 运行：pymol -cq scripts/install_plugin.py")
return
try:
# 无参数：声明第一个空闲端口，以便第二个 PyMOL 获取其自己的监听器，而不是无声地拥有一个。
if plugin.start_socket_server():
print(f"MCP 套接字插件自动启动在端口.current_port}")
else:
print("MCP 套接字监听器未启动；范围内每个端口都在使用中。")
except Exception as e:
print(f"MCP 套接字自动启动失败：{e}")
# 后台线程，因此 PyMOL 启动不会被阻止
threading.Thread(target=_auto_start_mcp_socket, daemon=True).start()
```
## 用法
### 启动连接
套接字监听器运行（步骤 5）后：
- **Claude Desktop：** 点击聊天时在工具部分出现的锤子图标；点击它即可访问 PyM工具。
- **Claude Code（CLI）：** 在终端中启动新会话。
### 示例命令
以下是您可以要求 Claude 执行的一些示例：
- "加载 PDB 1UBQ 并显示为卡通"
- "按二级结构显示蛋白质颜色"
- "用棍状表示法突出显示活性位点残基"
- "对齐两个结构并显示它们之间的差异"
- "计算这两个残基之间的距离"
- "将此视图保存为高质量图像"
### 多个 PyMOL 实例
每个 PyMOL 都声称其自己的端口，因此您可以运行多个实例并驱动任意一个。要求 Claude 列出它们，然后指定您要的
```
> 列出 PyMOL 实例
9876, pid 4412: 1ubq
instance=9877, pid 4488: 6vxx
> 在 9877 中，将链 A 颜色设为红色
```
当运行多个 PyMOL 实例时，Claude 必须被定向到正确的实例。
### PyMOL 技能
`make install` 还从 `skills/pymol-mcp/` 安装了一项技能，该技能为 Claude Code 和 Codex 提供了关于驱动此 MCP 服务器的高级指导。要单独安装它：
```bash
make install-skill
```
它进入 `~/.claude/skills/` 和 Codex 的 `~/.agents/skills/`，因此它适用于任何项目目录。之后请重启客户端会话。
### 会话历史记录命令在运行时都会被写入磁盘，因此 PyMOL 关闭后会话仍然存在。`~/.pymol-mcp/` 中的两个文件| 文件 | 内容 |
|---|---|
| `history.jsonl` | 每个命令及其参数、结果和任何错误 |
| `session-<timestamp>.pml` | 仅成功的命令，以 PyMOL 语法表示 |
重放会话，或将其重用为图形脚本：
```bash
pymol -r ~/.pymol-mcp/session-20260722-114646.pml
```
`load`、`save` 和 `png` 也记录了它们所触及的绝对路径，因为 PyMOL 将相对路径解析为其自己的工作目录。
将 `PYMOL_MCP_HISTORY=/some/dir` 设置为写入其他位置，或将 `PYMOL_MCP_HISTORY=off` 设置为禁用。该变量从启动 PyMOL 的环境中读取。
## 故障排除
- **连接问题：** 确保 PyMOL 插件在尝试从 Claude 连接之前正在监听
- **命令错误：** 在 PyMOL 输出窗口中检查任何错误消息
- **PyMOL 启动时“MCP 套接字安装”**，运行 `pymol -cq scripts/install_plugin.py`
- **对话框显示“未监听端口正在使用中**：您的 `~/.pymolrc.py` 加载插件按文件路径，给对话框和监听器提供了模块的单独副本。使用[步骤 5](#步骤-5-启动-pymol-套接字监听器) 中的代码段。
- **`~/.pymolrc.py` 被忽略**：PyMOL 在其工作目录之前搜索 `$HOME`，并在找到第一个保存 `pym*` 或 `.olrc*` 的目录后停止，因此从此类目录启动会遮蔽您的主目录配置。要打印 PyMOL 加载的文件： ```bash
pymol -cq -d "import pymol.invocation as i; print(i.get_user"
```
-未出现：** PyMOL 并检查插件是否正确安装
-aude 未连接：您的 Claude 配置文件中的路径是否正确
- **客户端显示混乱：** PyMOL 写入其启动的终端，这会破坏终端客户端（如 Claude Code）的显示。从其桌面图标或单独的终端启动 PyMOL。
- **服务器诊断：** 服务器默认情况下不记录任何内容，因为 MCP 客户端将 stdio 服务器的 stderr 视为错误流并显示每一行。将 `PYMOL_MCP_LOG_LEVEL=INFO`（或 `DEBUG`）设置为服务器的 `env` 块中以重新开启日志记录。
## 安全
监听器绑定到 localhost 并且没有身份验证，因此任何本地进程都可以通过它驱动 PyMOL。
`alter` 和 `alter_state` 需要 PyMOL 评估的表达式作为 Python。插件首先解析这些表达式，并仅允许对原子属性进行算术运算，拒绝属性访问、下标 和列表推导。
## 限制
- 字连接要求 PyMOL 和 Claude 都在机器上运行
- 一些复杂操作可能需要分解为更简单的步骤
- 使用实验性功能前，请始终保存您的工作
## 贡献
欢迎请随时提交拉取请求。
```
src/pymol_mcp/ MCP 服务器和模型；入口pymol-mcp`
pymol-mcp-socket-plugin/ OL 插件（目录名称是 PyMOL 导入的模块名称，因此不能更改）
scripts/ install_plugin、install_pymolrc、install_skill
skills/pymol-mcp/ Code 技能
tests/ pytest 套件；conftest.py 模拟 MCP 框架
```
使用 uv 运行测试套件和 linter：
```uv run pytest
uv run ruff check .
```
或使用 Make：
```bash
make test
make lint
```
## 致谢
源自 [vrtejus/pymcp](https://github.com/vrtejus/pymol-mcp是 [nu Rajan Tejus](https://github.com/vrtejus 用允许列出的命令调度器替换了 `exec()`
- 添加了 Pydantic 模型、类型提示和测试套件 围绕 uv 重新设计了设置，并添加了 Claude Code CLI 说明
## 许可证
MIT。参见 [LICENSE](LICENSE) 文件。版权由原始作者和后续贡献者共同持有；原始版权声明被保留为许可证的要求。
