Skip to content
Back to search

agentic-pymol

A Model Context Protocol (MCP) server that exposes PyMOL as a typed tool surface to your agent (Claude Code/Desktop, Codex, or any MCP-compatible client)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Arcadia-Science/agentic-pymol with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Arcadia-Science/agentic-pymol'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/arcadia-science--agentic-pymol/badge.svg)](/listings/arcadia-science--agentic-pymol)

HTML

<a href="/listings/arcadia-science--agentic-pymol"><img src="/api/listings/arcadia-science--agentic-pymol/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For a video walkthrough of the setup, watch this explanation:

Requires:

* PyMOL 2.6+ * [uv](https://docs.astral.sh/uv/) * an MCP client, such as Claude Code or Claude Desktop

1. Clone and sync

git clone https://github.com/Arcadia-Science/agentic-pymol.git
cd agentic-pymol
uv sync

`uv sync` installs the `agentic-pymol` console script into `.venv/bin/agentic-pymol`.

2. Install the PyMOL plugin

In PyMOL:

1. Open **Plugin → Plugin Manager → Install New Plugin → Choose file…** 2. Select `pymol_plugin/__init__.py` from this repo. 3. Open **Plugin → agentic-pymol plugin → Start Listening**.

> [!WARNING] > PyMOL 3.1.0 built against PyQt6 (e.g. the current Homebrew `pymol` 3.1.0 on macOS) **crashes during the installation above**. This is an [upstream PyMOL bug](https://github.com/schrodinger/pymol-open-source/issues/498). If you encounter this issue, there is a **simple workaround** here: https://github.com/Arcadia-Science/agentic-pymol/issues/3#issuecomment-4673331480.

3. Register the MCP server

**Claude Code:**

claude mcp add --scope user pymol /absolute/path/to/agentic-pymol/.venv/bin/agentic-pymol

Verify the MCP server is registered:

claude mcp list

---

**Codex CLI:**

codex mcp add pymol -- /absolute/path/to/agentic-pymol/.venv/bin/agentic-pymol

Verify the MCP server is registered:

codex mcp list

---

**VS Code Copilot:**

Add the following to your User mcp.json (MCP: Open User Configuration)

    "agentic-pymol": {
      "type": "stdio",
      "command": "/absolute/path/to/agentic-pymol/.venv/bin/agentic-pymol"
    },

---

> [!NOTE] > Using a different MCP client? Please [open a GitHub issue](https://github.com/Arcadia-Science/agentic-pymol/issues), or even better, send a [pull request](https://github.com/Arcadia-Science/agentic-pymol/pulls) adding the registration instructions for your client.

**You've successfully installed Agentic PyMOL**. See the next section for how to use it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 176 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Agentic PyMOL
  2. https://github.com/user-attachments/assets/43524828-0fcc-44e5-bcd6-c912e7f865b1
  3. ## Description
  4. A lightweight Model Context Protocol (MCP) server that exposes PyMOL as a typed tool surface for general-purpose agents.
  5. Use it with Claude Code, Claude Desktop, Codex, or any MCP-compatible client to let your agent control an open PyMOL session, inspect molecular structures, run PyMOL-native analyses, and render what it sees.
  6. Agentic PyMOL is not an embedded chatbot and not a molecular workbench. It is a small bridge between a capable agent and the PyMOL session you already use.
  7. ## What you can do
  8. Ask your agent to use PyMOL directly:
  9. ```text
  10. * Fetch ubiquitin, show it as cartoon, color by secondary structure, and render a PNG.
  11. * Create a table of residues that are in contact with DNA in the DNA-binding protein 6EDC.
  12. * Load these two structures, align chain A, report the RMSD, and show the regions that moved the most.
  13. * Which of these 10 binders trigger a conformational shift in the target activation loop?
  14. ```
  15. For a brief showcase of abilities, see this 6-minute demonstration of how you can use Agentic PyMOL to conduct meaningful structural analysis with natural language:
  16. [![Agentic PyMOL demonstration](assets/youtube_demo.jpg)](https://www.youtube.com/watch?v=0peLwtqQX7I)
  17. ## Design goals
  18. - **Use the PyMOL you already have.** Works with your existing PyMOL installation; PyMOL 2.6+ is supported.
  19. - **No insular chatbot.** PyMOL is exposed to your general-purpose agent rather than wrapping PyMOL in its own chat interface.
  20. - **Two-way communication.** The agent can manipulate the live PyMOL session and read structured information back out for reasoning, answers, and downstream work.
  21. - **Typed over textual.** Return objects, chains, coordinates, distances, RMSDs, views, sequences, and errors as data -- not just “succeeded.”
  22. - **PyMOL-native first.** Stay focused on visualization, selection logic, geometry, alignments, rendering, and session inspection.
  23. - **Lightweight and composable.** Do not bundle docking, sequence search, conservation analysis, prediction services, or external biology APIs; let other tools handle those jobs.
  24. ## Install
  25. For a video walkthrough of the setup, watch this explanation:
  26. [![Agentic PyMOL setup walkthrough](assets/youtube_setup.jpg)](https://youtu.be/xhaW-id0eu0)
  27. Requires:
  28. * PyMOL 2.6+
  29. * [uv](https://docs.astral.sh/uv/)
  30. * an MCP client, such as Claude Code or Claude Desktop
  31. ### 1. Clone and sync
  32. ```bash
  33. git clone https://github.com/Arcadia-Science/agentic-pymol.git
  34. cd agentic-pymol
  35. uv sync
  36. ```
  37. `uv sync` installs the `agentic-pymol` console script into `.venv/bin/agentic-pymol`.
  38. ### 2. Install the PyMOL plugin
  39. In PyMOL:
  40. 1. Open **Plugin → Plugin Manager → Install New Plugin → Choose file…**
  41. 2. Select `pymol_plugin/__init__.py` from this repo.
  42. 3. Open **Plugin → agentic-pymol plugin → Start Listening**.
  43. > [!WARNING]
  44. > PyMOL 3.1.0 built against PyQt6 (e.g. the current Homebrew `pymol` 3.1.0 on macOS) **crashes during the installation above**. This is an [upstream PyMOL bug](https://github.com/schrodinger/pymol-open-source/issues/498). If you encounter this issue, there is a **simple workaround** here: https://github.com/Arcadia-Science/agentic-pymol/issues/3#issuecomment-4673331480.
  45. ### 3. Register the MCP server
  46. **Claude Code:**
  47. ```bash
  48. claude mcp add --scope user pymol /absolute/path/to/agentic-pymol/.venv/bin/agentic-pymol
  49. ```
  50. Verify the MCP server is registered:
  51. ```bash
  52. claude mcp list
  53. ```
  54. ---
  55. **Codex CLI:**
  56. ```bash
  57. codex mcp add pymol -- /absolute/path/to/agentic-pymol/.venv/bin/agentic-pymol
  58. ```
  59. Verify the MCP server is registered:
  60. ```bash
  61. codex mcp list
  62. ```
  63. ---
  64. **VS Code Copilot:**
  65. Add the following to your User mcp.json (MCP: Open User Configuration)
  66. ```
  67. "agentic-pymol": {
  68. "type": "stdio",
  69. "command": "/absolute/path/to/agentic-pymol/.venv/bin/agentic-pymol"
  70. },
  71. ```
  72. ---
  73. > [!NOTE]
  74. > Using a different MCP client? Please [open a GitHub issue](https://github.com/Arcadia-Science/agentic-pymol/issues), or even better, send a [pull request](https://github.com/Arcadia-Science/agentic-pymol/pulls) adding the registration instructions for your client.
  75. **You've successfully installed Agentic PyMOL**. See the next section for how to use it.
  76. ## How to use
  77. Before your agent can control PyMOL, you must tell the plugin to start listening. **You have to do this each PyMOL session**. In PyMOL, open *Plugin → agentic-pymol plugin → Start Listening*. This opens the socket that the MCP server connects to.
  78. ![Agentic PyMOL plugin](assets/plugin.png)
  79. You can also start it from PyMOL's prompt instead of the dialog, which is useful for scripted or headless sessions:
  80. ```python
  81. from pymol_plugin import start_listening, stop_listening
  82. start_listening(9877)
  83. ```
  84. `start_listening` returns once the accept thread is up; if the port turns out to be in use, that is reported in the log rather than through the return value.
  85. > [!NOTE]
  86. > Currently Agentic PyMOL supports **one** PyMOL session bridged to **one** MCP server. Multiple agent conversations can talk to that single PyMOL concurrently, but a single MCP server doesn't currently see more than one PyMOL session at a time. Multi-session support is a candidate future feature. Please open an issue if it would help your workflow.
  87. The plugin defaults to port 9877. You can choose a different port during the "start listening" dialog box in the PyMOL plugin, and setting the MCP server's `PYMOL_MCP_PORT` env var to match. For example, using Claude Code:
  88. ```bash
  89. $ export PYMOL_MCP_PORT=9870
  90. $ claude
  91. ```
  92. You can now communicate with PyMOL through your LLM. Test it out:
  93. ```text
  94. Fetch ubiquitin and color by secondary structure
  95. ```
  96. ## Similar projects
  97. Agentic PyMOL is not the first PyMOL/LLM integration. Agentic PyMOL is intentionally narrow: a lightweight, typed MCP bridge to the PyMOL installation you already use. These projects explore nearby ideas with different emphases.
  98. - [`vrtejus/pymol-mcp`](https://github.com/vrtejus/pymol-mcp) - Early demonstrator of the core value of connecting PyMOL to LLM agents through MCP. Agentic PyMOL builds on that idea with typed tool outputs, structured session readback, and shared-secret authentication.
  99. - [MCPymol](https://github.com/chemrich/MCPymol) - a PyMOL MCP server that leverages the MCP as a thin command tunnel to carry out specific visualization-oriented workflows. In comparison, Agentic PyMOL is focused on supporting a lightweight and unopinionated tool surface that returns structured data to the LLM.
  100. - [`nagarh/pymol-claude-code`](https://github.com/nagarh/pymol-claude-code) - a compact Claude Code-only MCP that controls PyMOL through its XML-RPC mode (`pymol -R`) that requires launching PyMOL from the command line. This shares the goal of giving agents live access to PyMOL, but opts for just three MCP tools (`run_command`, `run_python`, `pymol_get`). In contrast, Agentic PyMOL surfaces discoverable tools with structured readback.
  101. - [ChatMol](https://chatmol.github.io/ChatMol/) - a broader molecular-design assistant with a PyMOL plugin, PyMOL skill, Streamlit interface, Python package, and copilot-style workflows. It is closer to a molecular-agent environment than a bridge between your existing LLM agent and PyMOL. Creates an insular environment.
  102. - [`ravishar313/PyMolAI`](https://github.com/ravishar313/PyMolAI) - an AI-oriented fork of open-source PyMOL with a Qt chat panel, internal PyMOL tools, model-provider integration, and optional OpenBio tools. Creates an insular environment.
  103. - [`pymol-agent-bridge`](https://github.com/ANaka/pymol-agent-bridge) - an interesting MCP-less socket bridge that lets terminal-capable agents send Python/PyMOL commands to a live PyMOL session. `pymol-agent-bridge` is a CLI/library bridge.
  104. ## How to cite
  105. If you use/reference this tool in your research, please cite the following work:
  106. [Agentic PyMOL: Structural analysis in PyMOL through natural language](https://thestacks.org/publications/resource-agentic-pymol/)
  107. ```bib
  108. @article{Golden2026Agentic,
  109. author = {Golden, James R. and Kiefl, Evan},
  110. journal = {The Stacks},
  111. doi = {10.57844/arcadia-gsbx-phd2},
  112. year = {2026},
  113. month = {jun 3},
  114. publisher = {Radial},
  115. title = {Agentic {PyMOL}: Structural analysis in {PyMOL} through natural language},
  116. url = {https://thestacks.org/publications/resource-agentic-pymol/v1},
  117. }
  118. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.