Skip to main content
Glama
ChimeraX MCP Server

ChimeraX MCP Server

by mahynotch

ChimeraX MCP Server

PyPI License: MIT Python 3.10+

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"

Structure workflow

Mutate Residue

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

Mutation workflow

Electrostatic & Hydrophobicity Surfaces

"Load 1AKI, show surface, color by electrostatic potential, then switch to hydrophobicity"

Electrostatic surface

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:48 and /A:48 spec formats, both 1-letter and 3-letter amino acid codes

  • Video recording -- capture sessions as MP4, record turntable spins

  • Run custom scripts -- execute .cxc and .py scripts 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 8765

To use a custom ChimeraX install location, set the CHIMERAX_BIN environment variable:

export CHIMERAX_BIN="/path/to/ChimeraX"

Installation

pip install chimerax-mcp

From GitHub (latest dev):

pip install git+https://github.com/mahynotch/chimerax-mcp.git

From 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-mcp

Edit config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.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.json

  • Windows: %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-mcp

Quick 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:

  1. open_structure("6VXX") -- fetches the structure from RCSB

  2. color_structure("#1", "chain") -- colors each chain differently

  3. show_surface("#1") -- displays the molecular surface

  4. zoom_to("/A:501") -- centers the view on residue 501 of chain A

Available Tools (39)

Structure (6)

Tool

Description

open_structure

Open PDB ID, file path, or URL

close_structure

Close one or all models

save_structure

Save to PDB/mmCIF/mol2

list_models

List all open models

get_sequence

Get amino acid sequence for a chain

run_script

Execute a .cxc or .py script

Editing (4)

Tool

Description

mutate_residue

Swap residue using Dunbrack rotamer library

delete_atoms

Delete atoms or residues

add_hydrogen

Add hydrogens (protonate)

minimize_energy

Run energy minimization

Visualization (18)

Tool

Description

color_structure

Color by scheme (chain, bfactor, rainbow) or named/hex color

show_electrostatic_surface

Coulombic ESP (red=negative, blue=positive)

show_hydrophobicity_surface

Molecular Lipophilicity Potential

show_surface

Show molecular surface with optional transparency

hide_surface

Hide molecular surface

show_cartoon

Show ribbon/cartoon

show_sticks

Show stick representation

hide_atoms

Hide atoms

zoom_to

Zoom camera to a selection

set_background

Set background color

label_residues

Add text labels to residues

clear_labels

Remove all labels

reset_view

Reset to default camera view

take_snapshot

Save PNG screenshot

start_recording

Begin recording session as video

stop_recording

Stop recording and save to MP4/WebM/MOV

spin

Rotate model around an axis

record_spin

Record a full turntable spin video

Measurement (6)

Tool

Description

measure_distance

Distance between two atoms (Angstroms)

measure_angle

Bond angle from three atoms (degrees)

align_and_rmsd

Structural alignment with RMSD

find_contacts

Residues within N Angstroms of selection

get_bfactors

B-factor values for selection

measure_buried_area

Buried solvent-accessible surface area

Selection (5)

Tool

Description

select_atoms

Select by ChimeraX specifier

select_near

Select within distance

select_chain

Select entire chain

invert_selection

Invert current selection

name_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, system are rejected

  • Script execution validated -- run_script only accepts existing .cxc/.py files with path validation

  • Local-only -- REST API listens on 127.0.0.1 only, 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 -v

Security 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:

  1. Install the package:

pip install chimerax-mcp
  1. Register the MCP server (detect the user's tool and run the appropriate command):

Tool

Command

Claude Code

claude mcp add -s user chimerax -- chimerax-mcp

Cursor

Add to ~/.cursor/mcp.json

VS Code

Add to .vscode/mcp.json

For Cursor / VS Code / others, create or update the config file with:

{
  "mcpServers": {
    "chimerax": {
      "command": "chimerax-mcp"
    }
  }
}
  1. Restart the AI tool to load the new MCP server.

  2. 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 tools
add_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

    A3.5/5.0

    Scored across 39 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for controlling UCSF ChimeraX molecular visualization software, enabling command execution, screenshots, structure analysis reports, and session management.
      27
      2
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      A Model Context Protocol server that lets you drive PyMOL with natural language, enabling structure loading, analytical views, measurements, and protein exploration through AI assistants.
      135
      17
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      5
      MIT