molcompose-mcp

Download statistics: Totals (Pepy). These are package downloads, not unique users or MCP calls.

An MCP stdio server for protein-interface analysis and molecular visualization in UCSF ChimeraX. Agents use the same MolCompose commands as the graphical panel.

Installation

Requires Python 3.11+, ChimeraX 1.12 and the MolCompose bundle. Install the latest published bridge:

python -m pip install --upgrade molcompose-mcp

This README describes MCP 0.1.2 with bundle 0.1.3, not yet published. For this checkout, run python -m pip install ./mcp from the repository root and install the matching bundle using the checkout instructions.

In the MolCompose Agent tab

Open Tools → Structure Analysis → MolCompose, then select the Agent tab. Select an installed, signed-in Codex or Claude Code CLI, then ask a question. The tab starts the local bridge when needed and selects --profile assistant automatically.

External MCP client

Start the REST bridge in ChimeraX:

remotecontrol rest start port 3000 json true

Use the actual port printed by ChimeraX. Register this command in your MCP client:

molcompose-mcp --chimerax-url http://127.0.0.1:3000 --profile assistant

{
  "mcpServers": {
    "molcompose": {
      "command": "molcompose-mcp",
      "args": [
        "--chimerax-url", "http://127.0.0.1:3000",
        "--profile", "assistant"
      ]
    }
  }
}

Use the executable's absolute path if your client cannot find it. To generate configuration with the resolved path, run:

molcompose-mcp --chimerax-url http://127.0.0.1:3000 --profile assistant --print-config

Copyable prompts: Connection setup · Verify analysis and preview.

Assistant workflow

For structured results, continue only after status: completed; resolve needs_input, needs_confirmation or failed before retrying. render_preview returns an image instead, which requires visual inspection. Successful export alone does not establish figure quality.

For advanced integrations, use --profile expert (29 tools). Omitting --profile selects all (34 tools). The assistant profile has 7 tools. See the MCP reference for individual tools, result fields and safety restrictions.

Importing energy data

Both load_energy and load_external_evidence accept solvation: "pb" or solvation: "gb". A file containing both methods requires a choice:

{"kind": "energy", "path": "/data/decomp.dat", "model": "#1", "chains": "A:A,B:B", "solvation": "pb"}

This example is for load_external_evidence; omit kind for load_energy. Match the chain mapping to your structure. Imported energies are not recalculated.

Troubleshooting

• Connection: keep ChimeraX open and use its actual REST port. Call inspect_session to check bundle/bridge compatibility.
• Preview or export: use windowed ChimeraX on macOS, not --nogui.
• Missing metric: check skipped and the required structure or input files.
• Overwrite or upload: assistant tools ask for confirmation. For PythiaStudio, configure PYTHIASTUDIO_API_KEY; local imports are not uploaded.
• Local access: the REST bridge is unauthenticated. Stop it with remotecontrol rest stop when finished. MCP input validation is not a host sandbox.

Source and documentation · BSD-3-Clause license