MCPymol：PyMOL的MCP服务器
Nucleosome core particle (1AOI) visualized with MCPymol's ghost heart style
MCPymol 的 是一个模型上下文协议（MCP）服务器，它提供了一个对话界面，用于使用PyMOL查看和分析蛋白质结构。它将PyMOL强大的分子可视化功能暴露给人工智能助手（如Claude），使您能够使用自然语言无缝加载结构、操纵视图和探索蛋白质。例如，我通过在Claude Code中键入以下提示来制作上面的图像：“给我看一个核小体”。从字面上看，就是这样。
几句话。.. 让我们面对现实吧。Pymol很棒，但使用起来很糟糕。语法非常模糊，虽然它的名字里有python，但它并不是python。这是为那些只想以简单、对话的方式观察结构并享受蛋白质乐趣的人准备的。
这段代码是使用Antigravity、Gemini Pro 3.1（直到我用完代币）和Claude code（Sonnet 4.6思维）的组合从头开始开发的。克劳德自鸣得意。双子座没有。你想读什么就读什么。所有的开发都是在macos上完成的，测试使用的是通过自制程序提供的开源pymol。它已经用Claude Code和Gemini CLI进行了测试。没有计划在其他型号/助手上进行测试。
名字 我高中时最好的朋友曾经和MC Chris合住一套公寓，他在《Aqua Teen Hunger》中为MC Pee Pants配音。我并不是说这是这个项目名称的灵感来源，但我也不否认。
🧬 它做什么
MCPymol充当AI助手和正在运行的PyMOL桌面实例之间的桥梁。它提供：
- 50+自动生成的PyMOL命令：Claude可以直接访问PyMOL原语，如
show,hide,color,distance,get_chains,select，以及更多。 - 智能多聚体和溶剂启发式：在获取或加载结构时，MCPymol会自动尝试获取 生物组装 （功能万用表）并应用 迭代广度优先搜索（BFS）式启发式算法 以隔离主万用表。从第一条链开始，它递归地添加可自定义半径内的所有相邻链（默认值 5.0Å)直到选择稳定。这确保了CRP五聚体或铁蛋白笼等大型圆形或庞大的组件保持完整，同时从晶胞中去除远处的晶体学副本。它还可以自动隐藏水、溶剂和非标准结晶添加剂，以获得干净、相关的视图。
- 双进程架构：为了绕过PyMOL的内部Python依赖限制，MCPymol通过两部分桥运行。原生PyMOL脚本在PyMOL应用程序中运行一个轻量级的后台套接字侦听器，而独立的FastMCP服务器处理与AI助手的通信。
🛠️ 预期用途
MCPymol专为结构生物学家、生物信息学家以及任何对蛋白质结构感兴趣并希望成为PyMOL自然语言对话伙伴的人而设计。你可以要求克劳德：
- “取泛素（1ubq）并将其显示为卡通。”
- “将阿尔法螺旋涂成红色，将贝塔螺旋涂成蓝色。”
- “测量残留物10和残留物20之间的距离。”
- “突出显示活动站点。”
💾 安装和配置
因为PyMOL需要自己的隔离Python环境来运行其GUI和渲染循环，所以使用MCPymol需要启动PyMOL插件并为您的AI助手配置外部MCP服务器。
1.启动原生PyMOL插件（所有设置都需要）
- 打开您的标准PyMOL桌面应用程序。
- 在PyMOL命令行中，手动初始化后台侦听器脚本。调整克隆存储库的路径：
run /path/to/MCPymol/src/mcpymol/plugin.py*您应该在PyMOL控制台中看到一条消息，指示插件正在监听 127.0.0.1:9876.*
💡 专业提示：自动启动插件 在PyMOL中运行初始化脚本的标准方式是通过其 pymolrc 资源文件。要在每次启动PyMOL时自动运行此插件，请添加以下内容 ~/.pymolrc.py:
import os, pymol
pymol.cmd.do("run /absolute/path/to/MCPymol/src/mcpymol/plugin.py")🔌 更改端口 默认端口为 9876。如果您需要同时运行多个MCP服务器，请用覆盖它 MCPYMOL_PORT 启动PyMOL之前的环境变量 和 桥：
# PyMOL (macOS example)
MCPYMOL_PORT=9867 open -a PyMOL
# MCP bridge/server
MCPYMOL_PORT=9867 uv run mcpymol______________________________________________________________________
2.配置您的AI助手
根据您的环境和首选的AI助手，选择以下设置之一。所有说明都假设您已将存储库克隆到您的计算机上。
git clone https://github.com/yourusername/MCPymol.git
cd MCPymol选项A：macOS与Claude Code CLI（使用 uv)
如果您在终端中使用Claude Code（即 claude CLI，而不是Claude Desktop应用程序）。
- 安装依赖项：
uv sync- 注册MCP服务器 在终端中运行以下命令：
claude mcp add mcpymol -- uv --directory /absolute/path/to/MCPymol run mcpymol- 启动新的Claude Code会话。确保PyMOL插件正在运行，并且您已准备好开始询问有关蛋白质结构的会话问题！
选项B：带克劳德桌面的macOS（使用 uv)
这是Claude Desktop应用程序用户使用的标准设置 uv 用于依赖性管理。
- 安装依赖项：
uv sync- 配置Claude桌面： 将以下内容添加到您的
claude_desktop_config.json文件：
{
"mcpServers": {
"mcpymol": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/MCPymol",
"run",
"mcpymol"
]
}
}
}- 重新启动克劳德桌面。确保PyMOL插件正在运行，并且您已准备好开始询问有关蛋白质结构的会话问题！
选项C:macOS与Gemini CLI（使用 uv)
这是Gemini CLI用户使用的标准、不受限制的设置 uv.
- 安装依赖项：
uv sync- 配置Gemini CLI： 在终端中运行以下命令：
gemini mcp add mcpymol uv --directory /absolute/path/to/MCPymol run mcpymol
gemini mcp refresh选项C:macOS在受限环境中（企业笔记本电脑）使用Gemini CLI
如果你在一台有管理的机器上运行 uv 如果受到安全策略的限制或阻止，则必须使用标准的Python虚拟环境。如果你在一个管理包存储库的环境中工作，你可能需要调整uv.lock中的一些地址，以符合你组织的规则。
- 创建并激活虚拟环境 使用现代Python版本（3.10+）：
python3 -m venv .venv
source .venv/bin/activate*（注意：macOS用户可能需要指定一个更新的python二进制文件，如 python3.11 如果系统默认值早于3.10）。*
- 安装软件包： 升级
pip要支持pyproject.toml安装，请从内部进行本机安装.venv:
pip install --upgrade pip
pip install -e .- 配置Gemini CLI： 将服务器添加到Gemini CLI，直接指向虚拟环境中生成的脚本：
gemini mcp add mcpymol /absolute/path/to/MCPymol/.venv/bin/mcpymol*（注意：如果在受限环境中配置Claude Code CLI，请直接指向venv二进制文件： claude mcp add mcpymol /absolute/path/to/MCPymol/.venv/bin/mcpymol).*
选项D：使用Gemini CLI在受限环境中运行Linux
如果你在一个严格管理标准python环境的托管Linux工作站上运行，你需要创建一个 venv 绕过这些限制。如果你在一个管理包存储库的环境中工作，你可能需要调整uv.lock中的一些地址，以符合你组织的规则。
- 验证您的PyMOL安装： 确保您已安装PyMOL，并可通过GUI访问。
sudo apt-get install pymol- 创建并激活虚拟环境：
cd MCPymol
python3 -m venv .venv
source .venv/bin/activate*（注意：如果您遇到错误 venv Debian/gLinux上缺少模块，您可能需要运行 sudo apt-get install python3-venv 第一）。*
- 将包依赖项本机安装到虚拟环境中：
pip install --upgrade pip
pip install -e .- 配置Gemini CLI： 将服务器添加到Gemini CLI，直接指向虚拟环境中生成的脚本：
gemini mcp add mcpymol /absolute/path/to/MCPymol/.venv/bin/mcpymol*（注意：确保您已运行 plugin.py 在测试服务器之前，请按照步骤1中的指示在PyMOL GUI窗口中使用本机脚本）。*
🧪 运行测试
该存储库包括一个严格的“谷歌工程师”等级 pytest 套件测试套接字有效负载生成和模拟PyMOL API执行边界。 要运行自动化测试，请执行以下操作：
PYTHONPATH=src uv run pytest tests/🎨 可视化视图
MCPymol包括一组高级可视化工具，这些工具超越了原始的PyMOL命令。每个视图都是为特定的分析任务设计的，可以通过单个自然语言请求调用。
______________________________________________________________________
ligand_view --绑定网站
演示： cAMP依赖性蛋白激酶（1ATP）与ATP
显示配体周围的结合口袋：口袋残基为带有标记CA原子的元素色棒，配体为黄色棒，氢键为黄色虚线，蛋白质为半透明卡通。
Show me the ATP binding site in 1ATPLigand view of ATP in cAMP-dependent kinase (1ATP)
______________________________________________________________________
interface_view --蛋白质-蛋白质界面
演示： Barnase–barstar复合体（1BRS），链A和D
颜色链A海洋蓝和链B鲑鱼。界面残留物（在合作伙伴4Å范围内）显示为带有侧链棒和CA标签的固体表面斑块。用黄色虚线绘制的交叉链氢键。
Show the interface between chain A and chain D in 1BRSInterface view of barnase–barstar complex (1BRS)
______________________________________________________________________
putty_view --B因子灵活性
演示： 泛素（1UBQ）
带B因子的管半径和色阶：蓝色=刚性/有序，红色=柔性/无序。70%透明的表面提供形状背景。
Show the B-factor flexibility of 1UBQ as a putty viewPutty view of ubiquitin (1UBQ)
______________________________________________________________________
hydrophobic_surface_view --表面化学
演示： *南极洲假丝酵母* 脂肪酶B（CalB，1TCA）
通过氨基酸化学特性对分子表面着色：橙色=疏水性，白色=极性，天蓝色=阳性，鲑鱼色=阴性。可用于识别疏水斑块、膜相互作用带和电荷互补性。CalB被合成化学家广泛用于对映选择性酯交换反应。
Show the hydrophobic surface of 1TCAHydrophobic surface view of Candida antarctica Lipase B, CalB (1TCA)
______________________________________________________________________
electrostatic_view --近似静电学
演示： 鸡蛋清溶菌酶（1LYZ）
使用pKa加权部分电荷通过残基级静电特性对分子表面着色：红色=负，白色=中性，蓝色=正。快速近似——无需外部工具。
Show the electrostatic surface of 1LYZElectrostatic view of lysozyme (1LYZ)
______________________________________________________________________
poisson_boltzmann_view --真实静电势
演示： 鸡蛋清溶菌酶（1LYZ）
先决条件： 这两个工具都必须安装在您的PATH在使用此视图之前。 ``bash # APBS (macOS via Homebrew) brew install brewsci/bio/apbs # PDB2PQR (via pip) pip install pdb2pqr``
Run a Poisson-Boltzmann electrostatics calculation on 1LYZPoisson-Boltzmann electrostatic surface of lysozyme (1LYZ)
______________________________________________________________________
crosslink_view --二硫键和金属配位
演示： 纤维素酶（1CEL）
突出显示结构交联：黄色为CYS侧链和二硫键，橙色为金属配位键。其余的蛋白质显示为薄薄的灰色卡通。
Show the disulfide bonds in 1CELCrosslink view of cellulase (1CEL)
______________________________________________________________________
pocket_view --装订袋表面
演示： HIV-1蛋白酶抑制剂MK1（1HSG）
将结合腔显示为化学性质着色的表面：橙色=疏水性，白色=极性，天蓝色=阳性，鲑鱼色=阴性。口袋侧链杆带有CA标签。配体呈现为黄色棒状。配体和口袋之间的氢键绘制为青色虚线。
Show the binding pocket around MK1 in 1HSGPocket view of MK1 binding site in HIV-1 protease (1HSG)
______________________________________________________________________
pharmacophore_view --配体药效团特征
演示： HIV-1蛋白酶抑制剂MK1（1HSG）
按药效团特征类型对配体进行着色：紫色=环/芳香碳，黄色=脂肪族碳，天蓝色=氮（氢键供体/受体），鲑鱼色=氧（氢键受体），金=硫，淡绿色=卤素。相互作用的残基侧链显示为带有CA标签的元素色棒。氢键与蛋白质结合，显示为青色虚线。
Show the pharmacophore features of MK1 in 1HSGPharmacophore view of MK1 in HIV-1 protease (1HSG)
______________________________________________________________________
mutation_view --突变热点
演示： 镰状细胞和相关突变E6V、K16E、V67F的人类血红蛋白（4HHB）
将蛋白质渲染为灰色卡通。变异的残留物侧链显示为带有白色CA标签的品红色棒。附近的残留物（4Å以内）显示为薄元素彩色棒，用于包装。接受标准突变符号（例如。 A123G).
Highlight mutations E6V, K16E, and V67F in hemoglobin (4HHB)