chimerax-mcp-plus

MCP server for controlling UCSF ChimeraX molecular visualization.

Features

• ChimeraX Control: Start, detect, and control ChimeraX via REST API

• Command Execution: Run any ChimeraX command

• Screenshot Capture: Take screenshots of the 3D view and tool windows

• Rich Log Output: Write trusted HTML and generated analysis reports to the ChimeraX Log

• API Reference: Search packaged/local ChimeraX docs and inspect live Python API symbols via safe runscript helpers

• Script Recipes: Search bundled runscript Python patterns, including JSON and rich-report payload examples

• View Management: Fit, rotate, and reset the view

• Session Management: Save and load ChimeraX sessions

Related MCP server: protein-design-mcp

Installation

# Global install (recommended)
uv tool install git+https://github.com/N283T/chimerax-mcp-plus

# Update
uv tool upgrade chimerax-mcp-plus

Configuration

Add to your MCP client configuration (e.g. ~/.claude/.mcp.json):

{
  "mcpServers": {
    "chimerax": {
      "command": "chimerax-mcp-plus"
    }
  }
}

Specifying a ChimeraX version

By default, the server auto-detects the latest installed ChimeraX. To use a specific version, set the CHIMERAX_PATH environment variable:

{
  "mcpServers": {
    "chimerax": {
      "command": "chimerax-mcp-plus",
      "env": {
        "CHIMERAX_PATH": "/Applications/ChimeraX-1.9.app/Contents/MacOS/ChimeraX"
      }
    }
  }
}

Recommended AI Client Workflow

AI clients such as Codex should use the MCP tools instead of launching ChimeraX directly from a shell. Before operating ChimeraX, call chimerax_guide once to read the recommended workflow, then use this sequence:

1. Call chimerax_status to check whether ChimeraX REST control is already available.

2. If ChimeraX is not running, call chimerax_start instead of launching ChimeraX directly.

3. Use MCP tools such as chimerax_open, chimerax_run, chimerax_models, screenshots, view, and session tools for operations.

4. Use chimerax_api_search, chimerax_api_read, chimerax_python_inspect, and script recipe tools before writing non-trivial ChimeraX Python scripts.

Direct shell launches can bypass the REST setup and leave the MCP client unable to control the session. Only launch ChimeraX directly when the user explicitly asks for that.

Available Tools

ChimeraX Control

Screenshot Management

Rich Log Output

chimerax_rich_log passes HTML through to ChimeraX with is_html=True; only use it with trusted input. chimerax_rich_report escapes plain text fields but allows raw HTML blocks for trusted local reports. Use theme="auto" to let generated reports follow the ChimeraX/system light or dark appearance where Qt WebEngine supports prefers-color-scheme; explicit theme="light" and theme="dark" remain available. Pass save_html_path to either rich-log tool to save the exact generated HTML locally; existing files require overwrite=true.

Rich report values can include structured ChimeraX command links without raw HTML. Use {"text":"#1/P:120", "spec":"#1/P:120", "action":"select"} for common actions (select, view, show, hide, metadata) or {"text":"open view", "command":"view #1/P:120"} for an explicit command. Links are rendered as cxcmd: anchors in the ChimeraX Log. Safe external database links can use {"text":"P00698", "url":"https://www.uniprot.org/uniprotkb/P00698/entry"}; only http and https URLs are linked. By default, rich-report URL links are converted to ChimeraX runscript command links that open the URL in the system default browser. Pass external_link_target="chimerax" to keep direct HTTP(S) links for ChimeraX's built-in browser/help viewer.

API Reference and Python Introspection

Static lookup uses CHIMERAX_DOCS_PATH first, then detected local ChimeraX docs, then repository-local skill docs when running from a checkout, and finally the packaged fallback index. Live introspection requires ChimeraX to be running and accepts only dotted symbols such as chimerax.atomic.AtomicStructure; it does not expose arbitrary Python evaluation.

Script Recipes

Recipes are static examples and are not executed by these tools. They are intended to help an LLM write trusted ChimeraX Python scripts after consulting chimerax_api_read or chimerax_python_inspect. Some recipes emit CHIMERAX_MCP_RESULT_JSON=... marker lines for downstream parsing; recipes with output_kind="rich_report_payload" produce payloads shaped for chimerax_rich_report. Official RBVI ChimeraX Recipes are referenced as links where useful, but this package bundles its own short MCP-oriented examples.

View Management

Structure Management

Structure Reports with External Annotations

chimerax_structure_report renders a ready-to-read ChimeraX Log report from structure metadata plus optional external annotations. It is designed to pair well with Togo MCP: fetch UniProt/PDB annotations with Togo MCP, normalize them to external_features, then pass them to ChimeraX MCP for residue mapping and clickable display.

Example for hen egg-white lysozyme (PDB 1AKI, UniProt P00698), where the PDB chain is the mature protein and UniProt has signal peptide residues 1-18:

{
  "model_spec": "#1",
  "model_name": "1aki",
  "pdb_id": "1AKI",
  "chain_mappings": [
    {
      "chain_id": "A",
      "uniprot_accession": "P00698",
      "uniprot_start": 19,
      "uniprot_end": 147,
      "pdb_start": 1,
      "pdb_end": 129
    }
  ],
  "external_features": [
    {
      "type": "Active site",
      "uniprot_position": 53,
      "description": "Catalytic residue",
      "source_url": "https://www.uniprot.org/uniprotkb/P00698/entry#feature-viewer"
    }
  ],
  "external_link_target": "system"
}

The report includes RCSB, PDBe, PDBj, and UniProt URL links when IDs are provided. Mapped features become ChimeraX command links such as select #1/A:35 and view #1/A:35. External DB/source links open in the system default browser by default; set external_link_target to "chimerax" if you prefer ChimeraX's internal browser.

Useful Togo MCP / UniProt SPARQL template for feature annotations:

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX faldo: <http://biohackathon.org/resource/faldo#>
PREFIX uniprot: <http://purl.uniprot.org/uniprot/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?annType ?comment ?begin ?end WHERE {
  VALUES ?annType {
    up:Active_Site_Annotation
    up:Binding_Site_Annotation
    up:Metal_Binding_Annotation
    up:Site_Annotation
  }
  uniprot:P00698 up:annotation ?ann .
  ?ann a ?annType .
  OPTIONAL { ?ann rdfs:comment ?comment . }
  OPTIONAL {
    ?ann up:range ?range .
    OPTIONAL { ?range faldo:begin/faldo:position ?begin . }
    OPTIONAL { ?range faldo:end/faldo:position ?end . }
  }
}
ORDER BY ?begin

How It Works

This MCP server communicates with ChimeraX via its REST API:

1. ChimeraX is started with remotecontrol rest start port 63269 json true log true

2. Commands are sent via HTTP GET to http://127.0.0.1:63269/run?command=...

3. Running-state checks use http://127.0.0.1:63269/cmdline.html so routine MCP calls do not spam the ChimeraX Log with version

4. Results are parsed and returned to the AI client

Rich Log Examples

Low-level trusted HTML:

{
  "html": "<p><b>RMSD:</b> 1.42 Å</p>",
  "title": "Alignment summary"
}

Themed block-composer report:

{
  "title": "Carbonic Anhydrase II active-site snapshot",
  "subtitle": "PDB 1CA2 · Zn²⁺ metalloenzyme",
  "theme": "auto",
  "accent_color": "#58a6ff",
  "save_html_path": "/tmp/ca2-report.html",
  "blocks": [
    {
      "type": "cards",
      "items": [
        {"label": "Model", "value": "#1 · 1CA2"},
        {"label": "Resolution", "value": "2.0 Å"},
        {"label": "Cofactor", "value": "Zn²⁺", "color": "#ffd33d"}
      ]
    },
    {
      "type": "table",
      "title": "Functional feature map",
      "columns": ["Feature", "Residues", "View"],
      "rows": [
        [
          "Active-site shuttle",
          "His64",
          {"text": "red", "style": "background:#da3633;color:white;font-weight:800;"}
        ],
        [
          "Zn²⁺ ligands",
          "His94, His96, His119",
          {"text": "orange", "style": "background:#fb8500;color:white;font-weight:800;"}
        ]
      ]
    },
    {
      "type": "progress",
      "label": "Active-site completeness",
      "value": 4,
      "max": 4,
      "color": "#238636"
    },
    {
      "type": "columns",
      "items": [
        {"type": "paragraph", "text": "Left column narrative."},
        {"type": "paragraph", "text": "Right column notes."}
      ]
    },
    {
      "type": "callout",
      "tone": "warning",
      "title": "Note",
      "text": "Raw HTML blocks are allowed for trusted local reports."
    }
  ]
}

Structured command-link table cell:

{
  "type": "table",
  "title": "Clickable residues",
  "columns": ["Model", "Residue", "Action"],
  "rows": [
    [
      {"text": "#1", "spec": "#1", "action": "select"},
      {"text": "P:120", "spec": "#1/P:120", "action": "select"},
      {"text": "view", "spec": "#1/P:120", "action": "view"}
    ]
  ]
}

Script Recipe Examples

Find recipes that produce rich-report payloads:

{
  "query": "structure summary",
  "category": "rich_report",
  "output_kind": "rich_report_payload",
  "limit": 5
}

Read the recipe script:

{
  "recipe_id": "structure_summary_rich_report_payload",
  "include_script": true,
  "max_chars": 8000
}

A rich-report recipe emits a CHIMERAX_MCP_RESULT_JSON= line containing a payload with title and blocks. After extracting that payload, pass it to chimerax_rich_report to display a styled report in the ChimeraX Log.

API Reference Examples

Search packaged or local ChimeraX API metadata:

{
  "query": "AtomicStructure residues",
  "kind": "modules",
  "limit": 5
}

Read a static documentation entry:

{
  "target": "atomic",
  "max_chars": 4000
}

Inspect a live ChimeraX Python API symbol:

{
  "symbol": "chimerax.atomic.AtomicStructure",
  "include_dir": true,
  "max_doc_chars": 4000
}

Requirements

• UCSF ChimeraX

• Python 3.12+

Security Considerations

This MCP server provides powerful capabilities that should be used with caution:

• Command Execution: chimerax_run can execute arbitrary ChimeraX commands, including Python code via runscript and shell commands via shell

• File System Access: Tools can read and write files accessible to ChimeraX

• Network Access: ChimeraX can fetch structures from remote servers

Recommendations:

• Only use with trusted AI assistants and prompts

• Run in a sandboxed environment for untrusted use cases

• Review commands before execution in sensitive environments

License

MIT