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 · Manuscript case · MCP setup
These instructions cover bundle 0.1.3 and MCP 0.1.2. 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- Open a complex, for example
open 1brs. - Select it under Structure, then open the Interface tab.
- Choose chains A and D and click Characterise Interface.
- Inspect the results and choose a style in Compose.
- 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.
- Install the matching bundle and MCP package as above.
- Open Agent and select an installed, signed-in Codex or Claude Code CLI. If it is not detected, choose its absolute path under Setup.
- Ask a question. The first send starts the local bridge when needed and uses
the
assistantprofile.
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.
Copy the 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.
Residue-level views of the barnase–barstar example. Prediction confidence is shown on an AF3 model; imported values use their corresponding structures.
The Interface and Agent tabs
- 1BRS demonstration: barnase–barstar structures and inputs for a compact introduction to MolCompose.
- Der f 7–binder2 manuscript case: design and 9HAE reference structures, AF3 inputs and predictions, Pythia-PPI results, MD analysis parameters and results, numerical source tables, and replay scripts. See the reproduction instructions.
Manuscript case data, replay scripts, and the full example dataset are available on Zenodo. The scripts reproduce MolCompose analyses from stored inputs and results; they do not rerun AF3 or MD simulations.
MolCompose code is distributed under the BSD-3-Clause license. Third-party case data retain their original terms; see the case NOTICE and AF3 terms.
A manuscript describing MolCompose has been submitted.