Detect ChimeraX installation on this system.

Returns the path to ChimeraX if found, or an error message if not.

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.

Stop the ChimeraX process started by this server.

Returns: Status of the stop attempt.

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.

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.

Search static ChimeraX command/tutorial/Python API metadata.

Works without optional local skills via packaged index.

Read bounded static ChimeraX API documentation content.

Inspect a live ChimeraX Python API symbol.

List live ChimeraX Python API attributes for a symbol.

Search bundled ChimeraX Python script recipes.

Recipes are static examples for trusted runscript workflows; this tool does not execute Python code.

Read a bundled ChimeraX Python script recipe by ID.

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.

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.

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.

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.

Get list of currently open models in ChimeraX.

Returns: List of open models with their information.

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.

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.

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.

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.

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.

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.

Close models in ChimeraX.

Args: model_spec: Model specification (default: "all")

Returns: Result of the close command.

Save the current ChimeraX session.

Args: path: Path to save the session file (.cxs)

Returns: Result of the save command.

Open a saved ChimeraX session.

Args: path: Path to the session file (.cxs)

Returns: Result of the open command.

List all screenshots saved by chimerax-mcp.

Returns: List of screenshot files with their details (path, size, modification time).

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.