Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@chimerax-mcp-plus show protein structure 1ubq"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for controlling UCSF ChimeraX molecular visualization.
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
# Global install (recommended)
uv tool install git+https://github.com/N283T/chimerax-mcp-plus
# Update
uv tool upgrade chimerax-mcp-plusAdd to your MCP client configuration (e.g. ~/.claude/.mcp.json):
{
"mcpServers": {
"chimerax": {
"command": "chimerax-mcp-plus"
}
}
}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"
}
}
}
}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:
Call chimerax_status to check whether ChimeraX REST control is already available.
If ChimeraX is not running, call chimerax_start instead of launching ChimeraX directly.
Use MCP tools such as chimerax_open, chimerax_run, chimerax_models, screenshots, view, and session tools for operations.
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.
Tool | Description |
| Return the recommended AI-client workflow for using ChimeraX through MCP instead of direct shell launches |
| Detect ChimeraX installation |
| Start ChimeraX with REST API enabled (supports |
| Stop the ChimeraX process |
| Check if ChimeraX is running without logging |
| Execute any ChimeraX command |
| List open models |
Tool | Description |
| Capture screenshot of the 3D view |
| Capture screenshot of a tool window |
| List all saved screenshots |
| Delete old screenshots (e.g., |
Tool | Description |
| Write trusted caller-provided HTML to the ChimeraX Log, optionally saving the generated HTML |
| Compose a themed rich HTML report from flexible blocks such as cards, tables, progress bars, columns, badges, callouts, legends, and raw HTML |
| Compose a structure report with RCSB/PDBe/PDBj/UniProt URL links plus caller-provided UniProt feature annotations mapped to clickable ChimeraX residue links |
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.
Tool | Description |
| Search static ChimeraX command, tutorial, and Python API module metadata; works without optional skills by using a packaged lightweight index |
| Read a static documentation entry from local docs when available, or return the packaged metadata summary |
| Inspect a live ChimeraX Python API symbol via |
| List attributes of a live ChimeraX Python API symbol with optional substring filtering |
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.
Tool | Description |
| Search bundled ChimeraX |
| Read a bundled recipe, including metadata, related API queries, optional official references, and the script body |
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.
Tool | Description |
| Fit all models or focus on a target |
| Rotate the view around an axis |
| Reset display to clean default state |
Tool | Description |
| Open a structure file or fetch from PDB; local paths are quoted for ChimeraX, including paths with spaces |
| Close models |
| Save session |
| Load session |
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 ?beginThis MCP server communicates with ChimeraX via its REST API:
ChimeraX is started with remotecontrol rest start port 63269 json true log true
Commands are sent via HTTP GET to http://127.0.0.1:63269/run?command=...
Running-state checks use http://127.0.0.1:63269/cmdline.html so routine MCP calls do not spam the ChimeraX Log with version
Results are parsed and returned to the AI client
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"}
]
]
}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.
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
}Python 3.12+
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
MIT
Read bounded static ChimeraX API documentation content.
Inputs: target (required), max_chars. Returns: object
Search static ChimeraX command/tutorial/Python API metadata.
Works without optional local skills via packaged index.
Inputs: query (required), kind, limit. Returns: object
Delete old screenshots to free up disk space.
Args: older_than_days: Delete screenshots older than this many days (default: 7). Set to 0 to delete all screenshots.
Returns: Number of deleted files and freed space.
Inputs: older_than_days. Returns: object
Close models in ChimeraX.
Args: model_spec: Model specification (default: "all")
Returns: Result of the close command.
Inputs: model_spec. Returns: object
Detect ChimeraX installation on this system.
Returns the path to ChimeraX if found, or an error message if not.
Inputs: no named parameters. Returns: object
Return the recommended workflow for AI clients using ChimeraX MCP.
Call this before operating ChimeraX from an AI client. It describes how to avoid bypassing the MCP server with direct shell launches and how to start, inspect, and control ChimeraX through MCP tools.
Inputs: no named parameters. Returns: object
List all screenshots saved by chimerax-mcp.
Returns: List of screenshot files with their details (path, size, modification time).
Inputs: no named parameters. Returns: object
Get list of currently open models in ChimeraX.
Returns: List of open models with their information.
Inputs: no named parameters. Returns: object
Open a structure file or fetch from PDB.
Args: path_or_id: Local file path, PDB ID (e.g., "1a0s"), or URL
Returns: Result of the open command.
Inputs: path_or_id (required). Returns: object
List live ChimeraX Python API attributes for a symbol.
Inputs: symbol (required), limit, filter. Returns: object
Inspect a live ChimeraX Python API symbol.
Inputs: symbol (required), include_dir, max_doc_chars. Returns: object
Reset the display to a clean default state.
Hides pseudobonds, atoms, and surfaces, then shows cartoon representation with heteroatom coloring, soft lighting, and fits the view.
Returns: Summary of reset commands executed.
Inputs: no named parameters. Returns: object
Write trusted HTML to the ChimeraX Log.
SECURITY NOTE: This tool passes caller-provided HTML through to ChimeraX
with is_html=True. Only use with trusted input.
Args:
html: HTML content to write to the ChimeraX Log.
level: Log level - info, warning, or error (default: info).
title: Optional escaped heading displayed above the HTML.
save_html_path: Optional local path where the generated HTML should be saved.
overwrite: If True, allow replacing an existing save_html_path.
Returns: Status of the rich log write operation.
Inputs: html (required), level, title, overwrite, +1 more. Returns: object
Compose a themed rich HTML report for the ChimeraX Log.
Plain text fields are escaped. Raw html block fields are trusted local
input and are inserted as-is.
Args:
title: Report title.
subtitle: Optional subtitle below the title.
theme: Visual theme - auto, dark, or light (default: auto).
accent_color: Optional primary accent color.
blocks: Ordered rich content blocks.
external_link_target: system opens safe external URL links in the
default browser via ChimeraX runscript command links;
chimerax leaves them as direct HTTP(S) links for ChimeraX's
built-in browser/help viewer.
level: Log level - info, warning, or error (default: info).
save_html_path: Optional local path where the generated HTML should be saved.
overwrite: If True, allow replacing an existing save_html_path.
Returns: Status of the rich report write operation.
Inputs: title (required), level, theme, blocks, +5 more. Returns: object
Execute a ChimeraX command through the MCP-managed REST connection.
Prefer this tool over shelling out to ChimeraX for routine commands.
SECURITY NOTE: This tool can execute arbitrary ChimeraX commands, including Python code execution via 'runscript' and shell commands via 'shell'. Only use with trusted input.
Args: command: The ChimeraX command to execute (e.g., "open 1a0s", "color red")
Returns: Command output or error message.
Inputs: command (required). Returns: object
Capture a screenshot of the current ChimeraX view.
Saves the image to a file and returns the file path. Use the Read tool on the returned path to view the image.
Args:
width: Image width in pixels (default: 1024, max: 8192)
height: Image height in pixels (default: 768, max: 8192)
format: Image format - png or jpg (default: png)
output_path: Where to save the image. If not provided, saves to
~/.local/share/chimerax-mcp/screenshots/ with a timestamp filename.
auto_fit: If True, run view to fit all models before capture (default: False).
If the view command fails, the screenshot is still taken.
Returns: File path to the saved screenshot image.
Inputs: width, format, height, auto_fit, +1 more. Returns: object
Read a bundled ChimeraX Python script recipe by ID.
Inputs: recipe_id (required), max_chars, include_script. Returns: object
Search bundled ChimeraX Python script recipes.
Recipes are static examples for trusted runscript workflows; this tool does not execute Python code.
Inputs: query (required), limit, category, output_kind. Returns: object
Open a saved ChimeraX session.
Args: path: Path to the session file (.cxs)
Returns: Result of the open command.
Inputs: path (required). Returns: object
Save the current ChimeraX session.
Args: path: Path to save the session file (.cxs)
Returns: Result of the save command.
Inputs: path (required). Returns: object
Start ChimeraX with REST API enabled.
AI clients should use this tool instead of launching ChimeraX directly from a shell, so the MCP server can enable and track REST control.
Args:
port: Port for REST API (default: 63269)
nogui: Run without GUI (default: False)
wait_seconds: Seconds to wait for startup (default: 15)
background: If True, return immediately and let ChimeraX start in background.
Use chimerax_status to check if ready. (default: False)
include_version: If True, run the ChimeraX version command once
after connecting and include it in the response. Defaults to False
to avoid writing version checks to the ChimeraX Log.
Returns: Status of the startup attempt.
Inputs: port, nogui, background, wait_seconds, +1 more. Returns: object
Check if ChimeraX REST server is running.
AI clients should call this before chimerax_start or other control tools
rather than probing ChimeraX by launching it directly.
Args:
include_version: If True, run the ChimeraX version command once
and include it in the response. Defaults to False to avoid writing
version checks to the ChimeraX Log.
Returns: Connection status and version if running.
Inputs: include_version. Returns: object
Stop the ChimeraX process started by this server.
Returns: Status of the stop attempt.
Inputs: no named parameters. Returns: object
Render a structure report with DB URLs and mapped feature links.
external_features is intended for annotations fetched by an external
source such as Togo MCP/UniProt SPARQL. Features with a UniProt position are
mapped onto ChimeraX residue specs using chain_mappings entries with
chain_id, uniprot_start, uniprot_end, pdb_start, and
pdb_end.
Inputs: level, theme, title, pdb_id, +10 more. Returns: object
Capture a screenshot of a ChimeraX tool window (e.g., Chain Contacts, Log).
This captures separate tool panels, not the main 3D view.
Use chimerax_screenshot for the main 3D view.
Args:
tool_name: Name of the tool window to capture (e.g., "Chain Contacts", "Log")
width: Optional width to resize the widget before capture (1-8192)
height: Optional height to resize the widget before capture (1-8192)
padding: Pixels of white padding around the image (default: 0, must be >= 0)
output_path: Where to save the image. If not provided, saves to
~/.local/share/chimerax-mcp/screenshots/ with a timestamp filename.
Returns:
Dict with status, tool_name, and file_path on success,
or status and message on error.
Inputs: tool_name (required), width, height, padding, +1 more. Returns: object
Rotate the view around an axis.
Args: axis: Axis to rotate around - "x", "y", or "z" (default: "y") angle: Rotation angle in degrees (default: 90) frames: Number of animation frames, must be >= 1 (default: 1, instant)
Returns: Result of the turn command.
Inputs: axis, angle, frames. Returns: object
Adjust the view to fit models or a specific target in the window.
Args: target: Optional atom specification to focus on (e.g., "#1", ":MK1"). If not provided, fits all models in the view.
Returns: Result of the view command.
Inputs: target. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 27 tools
Each tool has a clearly distinct purpose, from lifecycle management (start/stop/status/detect) to molecular operations (open/close/view/turn) and documentation lookup (api_search, api_read, python_inspect, python_dir). Even similar tools like rich_log vs rich_report are differentiated by composition vs direct writing, and screenshot vs tool_screenshot by target surface.
All tools share the chimerax_ prefix, but the remainder follows no single convention: some are bare verbs (open, close, run, start), some are nouns (models, status, view), and others are object_verb (api_search, session_save, list_screenshots). This mixed pattern is readable but not predictable.
With 27 tools, the count exceeds the 25+ threshold that the rubric marks as too many. The server covers a broad domain, but many tools (api_search, api_read, python_inspect, python_dir, script_recipe_search, script_recipe_read, guide) could potentially be consolidated or exposed via fewer, higher-level tools.
The tool surface covers the core ChimeraX lifecycle: starting/stopping, opening/closing models, running commands, saving/opening sessions, capturing screenshots, and generating reports. Minor gaps exist, such as no dedicated tool for atomic selection or model information retrieval, but these can be worked around via chimerax_run.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
MCP server for Drosophila neuroscience data from VirtualFlyBrain
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Remote MCP server for 4chems hosted IUCLID, CHESAR and QSAR Toolbox: onboarding, inquiries, admin.