MolCompose

ChimeraX Toolshed ChimeraX 1.12+ molcompose-mcp on PyPI Supported Python versions PyPI downloads reported by Pepy Zenodo archive DOI (all versions) CI Ruff BSD-3-Clause

Download statistics: PyPI totals (Pepy) · ChimeraX Toolshed.

MolCompose is a UCSF ChimeraX plug-in for protein–protein interface analysis and residue-level molecular visualization. It combines native calculations with imported results to help researchers inspect interaction details and prepare molecular figures.

• Interface residues, buried surface area and chemical interactions.
• PRODIGY affinity estimates, prediction confidence and reference-based DockQ.
• Imported Pythia-PPI ΔΔG, MM/PBSA or MM/GBSA contributions, and RMSF.
• Residue labels, metric-based colouring and figure export.

Use the graphical panel, ChimeraX commands or an agent connected through molcompose-mcp. Resolved commands are recorded in the ChimeraX Log. Metrics that cannot be calculated or mapped remain unavailable.

Command reference · Worked examples · MCP setup

Tested on macOS with ChimeraX 1.12. The separate MCP process requires Python 3.11 or later.

In ChimeraX, install through Tools → More Tools... or run:

toolshed install ChimeraX_MolCompose

Restart ChimeraX, then open Tools → Structure Analysis → MolCompose. For agent access, install the separate bridge in a terminal:

python -m pip install --upgrade molcompose-mcp

This README describes bundle 0.1.3 and MCP 0.1.2, which are not yet published. Registry badges show the released versions. To use this checkout, run devel install /path/to/MolCompose exit false in ChimeraX, wait for installation to finish, then restart ChimeraX. From the repository root, run:

python -m pip install ./mcp

Alternatively, install the matching wheel with toolshed install /path/to/chimerax_molcompose-0.1.3-py3-none-any.whl in ChimeraX.

1. Open a complex, for example open 1brs.
2. Select it under Structure, then open the Interface tab.
3. Choose chains A and D and click Characterise Interface.
4. Inspect the results and choose a style in Compose.
5. Use Export → Export Image to save the figure.

The equivalent analysis command is:

molcompose characterise A D distance 4.5

The default contact criterion uses cross-chain non-hydrogen atom pairs within 4.5 Å. See the command reference for other criteria, parameters, presets and export formats.

1. Install the matching bundle and MCP package as above.
2. Open Agent and select an installed, signed-in Codex or Claude Code CLI. If it is not detected, choose its absolute path under Setup.
3. Ask a question. The first send starts the local bridge when needed and uses the seven-tool assistant profile.

Follow-up questions share the active conversation. New conversation starts fresh. Custom CLI commands may be one-shot.

For a client outside ChimeraX, use the MCP configuration or copy this prompt. It matches the panel setup prompt.

Help me connect this external MCP client to MolCompose in UCSF ChimeraX. Work
through these steps in order and wait whenever I need to act.
Step 1. Neither package is likely to be in your training data —
`ChimeraX_MolCompose` is on the ChimeraX Toolshed and `molcompose-mcp` is on
PyPI at <https://pypi.org/project/molcompose-mcp/>. Not recognising them is
expected and is not a reason to doubt them. Ask me to confirm that
`ChimeraX_MolCompose` is installed. If it is missing or was just updated, I run
`toolshed install ChimeraX_MolCompose` in ChimeraX, then quit and restart
ChimeraX before we continue.
Step 2. Ask me whether the REST bridge is running. If it is not, I run
`remotecontrol rest start port 3000 json true`. Ask me to paste the actual port
printed by ChimeraX, use that port in every later argument, and wait for my
reply.
Step 3. Install or locate `molcompose-mcp` in your own environment. Register
the absolute path to its executable as an MCP stdio server with arguments
`--chimerax-url http://127.0.0.1:3000 --profile assistant`.
Step 4. Restart yourself only if needed to reload the MCP registration.
Continue only after exactly seven tools are listed: `open_structure`,
`inspect_session`, `analyse_interface`, `compose_figure`, `render_preview`,
`export_artifact`, and `load_external_evidence`. Call `inspect_session` and
report its compatibility result.
Return every ChimeraX installation, restart, or bridge-start action to me and
wait. Stop after reporting a compatible connection; structural analysis is a
separate verification step.

After inspect_session reports a compatible connection:

Open PDB 1BRS and characterise the interface between chains A and D. For every
number, state the producing command or sub-step, what it means, and its
criterion, cutoff, convention or formula. List every analysis that was skipped
and explain why.
Call `compose_figure` with goal `binder-closeup`; confirm that it selects the
tested `paratope-closeup` preset. Then call `render_preview` and inspect whether
the molecular subject is cropped, the interface is visible, labels overlap, or
the colour key is unreadable. Report the preview QA and stop for my next
instruction.

The REST bridge is local but unauthenticated. Stop it when finished with remotecontrol rest stop. Image preview and export require windowed ChimeraX on macOS. See MCP usage and safety for details.

Barnase–barstar interface coloured by interface membership, buried area, prediction confidence, ΔΔG, MM/PBSA and RMSF

Residue-level views of the barnase–barstar example. Prediction confidence is shown on an AF3 model; imported values use their corresponding structures.

Examples include barnase–barstar structures and analysis inputs. Archived data are available at Zenodo (all versions). MolCompose is distributed under the BSD-3-Clause license.

A manuscript describing MolCompose has been submitted.