ChimeraX MCP Server
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 Server load 6VXX, highlight residue A:501, and take a screenshot"
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.
ChimeraX MCP Server
Talk to proteins in natural language. This MCP server connects AI coding tools (Claude Code, Cursor, VS Code, etc.) to UCSF ChimeraX, letting you load, edit, visualize, and analyze protein structures through conversation -- no manual ChimeraX commands needed.
Just say "open 6VXX, mutate A:501 to Lys, color by hydrophobicity, and take a screenshot" and watch ChimeraX do it in real time.
This project is in early development and actively looking for contributors. Bug reports, feature requests, and pull requests are very welcome -- check out the issues page or open a PR!
Demos
Load & Visualize
"Load 3LJ5, show only chain A, make it publication-ready with rainbow coloring and transparent surface"

Mutate Residue
"Open 6VXX, zoom to residue A:501, highlight it, mutate Thr to Lys, show nearby residues"

Electrostatic & Hydrophobicity Surfaces
"Load 1AKI, show surface, color by electrostatic potential, then switch to hydrophobicity"

Related MCP server: chimerax-mcp-plus
Features
39 tools covering structure loading, editing, visualization, measurement, selection, and video recording
Auto-launches ChimeraX -- no manual setup needed, just install and go
Works with any MCP client -- Claude Code, Cursor, Windsurf, VS Code Copilot, Cline, OpenCode, Continue, Claude Desktop
Built-in agent instructions -- AI agents automatically learn ChimeraX spec syntax and common workflows
Security hardened -- command injection prevention, dangerous command blocking, script path validation
Accepts flexible input -- both
A:48and/A:48spec formats, both 1-letter and 3-letter amino acid codesVideo recording -- capture sessions as MP4, record turntable spins
Run custom scripts -- execute
.cxcand.pyscripts with path validation
Prerequisites
UCSF ChimeraX installed (download)
Python 3.10+
ChimeraX will be launched automatically when the first tool is called. No need to start it manually or enable the REST API yourself.
Open ChimeraX and run in its command line:
remotecontrol rest start port 8765To use a custom ChimeraX install location, set the CHIMERAX_BIN environment variable:
export CHIMERAX_BIN="/path/to/ChimeraX"Installation
pip install chimerax-mcpFrom GitHub (latest dev):
pip install git+https://github.com/mahynotch/chimerax-mcp.gitFrom source (development):
git clone https://github.com/mahynotch/chimerax-mcp.git
cd chimerax-mcp
pip install -e .MCP Configuration
After installing, add the server to your AI coding tool:
claude mcp add -s user chimerax -- chimerax-mcpEdit config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"chimerax": {
"command": "chimerax-mcp",
"args": []
}
}
}Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"chimerax": {
"command": "chimerax-mcp",
"args": []
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"chimerax": {
"command": "chimerax-mcp",
"args": []
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"chimerax": {
"type": "stdio",
"command": "chimerax-mcp"
}
}
}Use the "Edit MCP Settings" button in the Cline panel, or edit directly:
macOS:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonWindows:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
{
"mcpServers": {
"chimerax": {
"command": "chimerax-mcp",
"args": [],
"disabled": false
}
}
}Add to ~/.config/opencode/opencode.json or project opencode.json:
{
"mcp": {
"chimerax": {
"type": "local",
"command": ["chimerax-mcp"],
"enabled": true
}
}
}Add to .continue/config.yaml:
mcpServers:
- name: chimerax
type: stdio
command: chimerax-mcpQuick Start
Once configured, just talk naturally:
"Open 6VXX, color by chain, show surface, zoom to residue A:501"
The AI will call MCP tools sequentially and ChimeraX renders each step in real time:
open_structure("6VXX")-- fetches the structure from RCSBcolor_structure("#1", "chain")-- colors each chain differentlyshow_surface("#1")-- displays the molecular surfacezoom_to("/A:501")-- centers the view on residue 501 of chain A
Available Tools (39)
Structure (6)
Tool | Description |
| Open PDB ID, file path, or URL |
| Close one or all models |
| Save to PDB/mmCIF/mol2 |
| List all open models |
| Get amino acid sequence for a chain |
| Execute a |
Editing (4)
Tool | Description |
| Swap residue using Dunbrack rotamer library |
| Delete atoms or residues |
| Add hydrogens (protonate) |
| Run energy minimization |
Visualization (18)
Tool | Description |
| Color by scheme ( |
| Coulombic ESP (red=negative, blue=positive) |
| Molecular Lipophilicity Potential |
| Show molecular surface with optional transparency |
| Hide molecular surface |
| Show ribbon/cartoon |
| Show stick representation |
| Hide atoms |
| Zoom camera to a selection |
| Set background color |
| Add text labels to residues |
| Remove all labels |
| Reset to default camera view |
| Save PNG screenshot |
| Begin recording session as video |
| Stop recording and save to MP4/WebM/MOV |
| Rotate model around an axis |
| Record a full turntable spin video |
Measurement (6)
Tool | Description |
| Distance between two atoms (Angstroms) |
| Bond angle from three atoms (degrees) |
| Structural alignment with RMSD |
| Residues within N Angstroms of selection |
| B-factor values for selection |
| Buried solvent-accessible surface area |
Selection (5)
Tool | Description |
| Select by ChimeraX specifier |
| Select within distance |
| Select entire chain |
| Invert current selection |
| Save selection under a reusable name |
Security
Commands are sanitized before being sent to ChimeraX:
Command injection blocked --
;and newlines rejected (ChimeraX uses these as command separators)Dangerous commands blocked --
exec,shell,systemare rejectedScript execution validated --
run_scriptonly accepts existing.cxc/.pyfiles with path validationLocal-only -- REST API listens on
127.0.0.1only, not exposed to the network
Testing
Run the full test suite (53 tests) against a live ChimeraX instance:
pip install pytest
python -m pytest tests/test_live.py -vSecurity tests run without ChimeraX. Live tests auto-skip if ChimeraX is not available.
For AI Agents: Auto-Install
If a user asks you to install this MCP server, follow these steps:
Install the package:
pip install chimerax-mcpRegister the MCP server (detect the user's tool and run the appropriate command):
Tool | Command |
Claude Code |
|
Cursor | Add to |
VS Code | Add to |
For Cursor / VS Code / others, create or update the config file with:
{
"mcpServers": {
"chimerax": {
"command": "chimerax-mcp"
}
}
}Restart the AI tool to load the new MCP server.
Verify with a test call:
open_structure("1aki")
Important: Before proceeding, confirm with the user that UCSF ChimeraX is installed on their machine. If not, direct them to https://www.cgl.ucsf.edu/chimerax/download.html -- the server auto-launches ChimeraX but cannot install it.
Disclaimer
This project is not affiliated with, endorsed by, or sponsored by UCSF or the RBVI team. "ChimeraX" is a trademark of the University of California. This server communicates with ChimeraX through its public REST API and contains no ChimeraX source code.
Users are responsible for complying with ChimeraX's license terms. ChimeraX is free for academic and non-commercial use; commercial use requires a separate license from UCSF.
License
MIT -- see LICENSE
Available Tools
39 toolsadd_hydrogenC
Add hydrogens to the structure. Aliases: protonate, add H, hydrogenate.
Example: add_hydrogen("#1")
Inputs: spec. Returns: result
align_and_rmsdA
Align one selection to another and report RMSD. Uses ChimeraX 'align' command (no 'measure rmsd' exists). Aliases: align, superpose, RMSD, overlay, structural alignment.
Example: align_and_rmsd("#1/A", "#2/A")
Inputs: spec (required), to_spec (required). Returns: result
clear_labelsA
Remove all labels. Aliases: delete labels, hide labels, unlabel.
Example: clear_labels()
Inputs: no named parameters. Returns: result
close_structureA
Close one or all open models. Aliases: remove model, delete model, unload.
Example: close_structure("#1")
Inputs: model_id. Returns: result
color_structureA
Color atoms/residues by scheme (chain, bfactor, rainbow) or a named/hex color. For electrostatic or hydrophobicity coloring use the dedicated surface tools. Aliases: colour, paint, set color, recolor.
Example: color_structure("#1", "chain")
Inputs: spec (required), color_scheme (required). Returns: result
delete_atomsB
Delete atoms or residues matching the spec. Aliases: remove atoms, erase, cut.
Example: delete_atoms("/A:501")
Inputs: spec (required). Returns: result
find_contactsB
Find residues within N Angstroms of a selection. Aliases: contacts, neighbors, nearby residues, clashes.
Example: find_contacts("/A:501", 4.0)
Inputs: spec (required), distance. Returns: result
get_bfactorsB
Return B-factors for selected atoms. Aliases: B-factor, temperature factor, displacement.
Example: get_bfactors("/A:501")
Inputs: spec (required). Returns: result
get_sequenceA
Return amino acid sequence for a chain. Aliases: sequence, residues, chain sequence.
Example: get_sequence("/A")
Inputs: chain_spec (required). Returns: result
hide_atomsB
Hide atoms for a selection. Aliases: hide, conceal atoms.
Example: hide_atoms("/A:501")
Inputs: spec (required). Returns: result
hide_surfaceB
Hide molecular surface. Aliases: remove surface, surface off.
Example: hide_surface("#1")
Inputs: spec. Returns: result
invert_selectionA
Invert the current selection. Aliases: select inverse, flip selection.
Example: invert_selection()
Inputs: no named parameters. Returns: result
label_residuesC
Add text labels to residues. Default shows residue name + number. Aliases: annotate, tag residues, show labels.
Example: label_residues("/A:501")
Inputs: spec (required), label. Returns: result
list_modelsA
List all open models with IDs and names. Aliases: show models, what's open, loaded structures.
Example: list_models()
Inputs: no named parameters. Returns: result
measure_angleB
Measure bond angle defined by three atoms in degrees. Aliases: angle, bond angle.
Example: measure_angle("/A:501@N", "/A:501@CA", "/A:501@C")
Inputs: atom1 (required), atom2 (required), atom3 (required). Returns: result
measure_buried_areaA
Measure buried solvent-accessible surface area between two atom sets. Aliases: buried area, interface area, binding interface.
Example: measure_buried_area("#1/A", "#1/B")
Inputs: spec1 (required), spec2 (required). Returns: result
measure_distanceB
Measure distance between two atoms in Angstroms with visual annotation. Aliases: distance, how far, length between.
Example: measure_distance("/A:501@CA", "/A:31@CA")
Inputs: atom1 (required), atom2 (required). Returns: result
minimize_energyC
Run energy minimization on a model. Aliases: relax, optimize geometry, energy minimize.
Example: minimize_energy(100, "#1")
Inputs: steps, model_id. Returns: result
mutate_residueA
Mutate (swap) a residue to a different amino acid using the Dunbrack rotamer library. Accepts both 1-letter (K) and 3-letter (LYS) amino acid codes. Spec can be /A:48 or A:48 format. Aliases: swap, change residue, substitute, point mutation.
Example: mutate_residue("/A:501", "K")
Inputs: spec (required), new_aa (required). Returns: result
name_selectionB
Save current selection under a reusable name. Aliases: save selection, bookmark, name zone.
Example: name_selection("binding_site")
Inputs: name (required). Returns: result
open_structureA
Open a molecular structure from PDB ID, file path, or URL. Aliases: load, fetch, import, read structure.
Example: open_structure("6VXX")
Inputs: source (required). Returns: result
record_spinC
Record a full turntable spin and save as video in one step. Aliases: turntable video, spin video, rotation movie, 360 video.
Example: record_spin("/tmp/turntable.mp4")
Inputs: path (required), axis, frames, degrees, +1 more. Returns: result
reset_viewA
Reset to the default camera view. Aliases: home view, reset camera, default view.
Example: reset_view()
Inputs: no named parameters. Returns: result
run_scriptA
Run a ChimeraX command script (.cxc) or Python script (.py). File must exist locally with a .cxc or .py extension. Aliases: execute script, run cxc, run python script, source.
Example: run_script("/path/to/setup.cxc")
Inputs: path (required). Returns: result
save_structureC
Save a model to PDB, mmCIF, or mol2 file. Aliases: export, write structure, download.
Example: save_structure("/tmp/model.pdb", "#1")
Inputs: path (required), model_id. Returns: result
select_atomsB
Select atoms/residues by ChimeraX specifier string. Aliases: pick, highlight, sel, select.
Example: select_atoms("/A:501")
Inputs: spec (required). Returns: result
select_chainB
Select an entire chain. Aliases: pick chain, highlight chain.
Example: select_chain("A")
Inputs: chain (required). Returns: result
select_nearC
Select all atoms within N Angstroms of a selection. Aliases: select nearby, zone, within distance.
Example: select_near("/A:501", 5.0)
Inputs: spec (required), distance (required). Returns: result
set_backgroundA
Set the background color (white, black, hex). Aliases: background, bg color.
Example: set_background("white")
Inputs: color (required). Returns: result
show_cartoonC
Show ribbon/cartoon representation. Aliases: ribbon, cartoon, secondary structure.
Example: show_cartoon("#1")
Inputs: spec. Returns: result
show_electrostatic_surfaceC
Calculate and display Coulombic electrostatic potential on the surface. Aliases: electrostatics, ESP, charge surface, coulombic.
Example: show_electrostatic_surface("#1")
Inputs: spec, range_, palette. Returns: result
show_hydrophobicity_surfaceC
Calculate and display Molecular Lipophilicity Potential on the surface. Dark cyan = hydrophilic, dark goldenrod = hydrophobic. Aliases: hydrophobicity, lipophilicity, MLP, hydrophobic surface.
Example: show_hydrophobicity_surface("#1")
Inputs: spec. Returns: result
show_sticksA
Show stick representation for a selection. Aliases: sticks, ball and stick, show bonds.
Example: show_sticks("/A:501")
Inputs: spec (required). Returns: result
show_surfaceC
Show molecular surface. Aliases: surface, display surface, solvent-accessible surface.
Example: show_surface("#1", 0.7)
Inputs: spec, opacity. Returns: result
spinB
Spin/rotate the model around an axis (x, y, or z). Great for turntable animations when combined with recording. Aliases: rotate, turntable, orbit, spin around.
Example: spin("y", 360, 180)
Inputs: axis, frames, degrees. Returns: result
start_recordingB
Start recording a movie of the ChimeraX session. Call this before making visual changes, then stop_recording when done. Aliases: record, start movie, begin recording.
Example: start_recording()
Inputs: supersample. Returns: result
stop_recordingA
Stop recording and save movie to file (.mp4, .webm, .mov, .avi). Aliases: stop movie, save movie, end recording, save video.
Example: stop_recording("/tmp/session.mp4")
Inputs: path (required), framerate. Returns: result
take_snapshotB
Save a PNG screenshot of the current view. Aliases: screenshot, capture, save image, photo.
Example: take_snapshot("/tmp/snapshot.png")
Inputs: path (required). Returns: result
zoom_toB
Zoom the camera to center on a selection. Aliases: focus, center on, look at, zoom in.
Example: zoom_to("/A:501")
Inputs: spec (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Most tools have clearly distinct purposes, with descriptive aliases that reduce ambiguity. However, some overlap exists between selection and visualization tools (e.g., hide_atoms vs delete_atoms, multiple surface tools) which could cause minor confusion.
All tool names follow a consistent verb_noun pattern (e.g., open_structure, show_surface, measure_distance). Variations like align_and_rmsd are still intuitive and fit the pattern.
With 39 tools, the server covers a wide range of molecular visualization and analysis tasks, which is appropriate for its domain. While slightly high, each tool serves a distinct purpose and the count is justified.
The tool surface is comprehensive, covering structure I/O, visualization, selection, measurement, mutagenesis, energy minimization, and animation. There are no obvious gaps for typical molecular modeling workflows.
Maintenance
Related MCP Connectors
AI-powered bioprotocol optimization — generate, search, and manage lab protocols via MCP
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
MCP-Native LLM Orchestration Agent
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables control of VMD2 for molecular dynamics analysis through natural language, allowing users to load structures, set representations, measure distances, compute RMSD, and render images without Tcl scripting.8-
- AlicenseBqualityDmaintenanceMCP server for controlling UCSF ChimeraX molecular visualization software, enabling command execution, screenshots, structure analysis reports, and session management.272MIT
- AlicenseCqualityBmaintenanceA Model Context Protocol server that lets you drive PyMOL with natural language, enabling structure loading, analytical views, measurements, and protein exploration through AI assistants.13517MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control RELION 5.x cryo-EM structure determination software through natural language, providing 23 tools for the complete single-particle analysis pipeline.5MIT