rosetta-mcp-server

<p align="center"> <img src="./assets/banner2.png" width="100%" alt="Rosetta MCP Server" /> </p>

Rosetta MCP Server

Author: Ariel J. Ben-Sasson

A Model Context Protocol (MCP) server that lets Cursor (or any MCP client) work with Rosetta, PyRosetta, and Biotite: run RosettaScripts, validate XML protocols, translate between Rosetta and Biotite, score structures, and query documentation -- all from your AI coding assistant.

What's new in v1.3.0 (vs v1.1.8 on npm)

New: Biotite integration

• rosetta_to_biotite -- Find the Biotite equivalent of any Rosetta function with working example code (21 mappings covering structure I/O, SASA, RMSD, superimposition, secondary structure, contacts, hydrogen bonds, B-factors, angles, and more)
• biotite_to_rosetta -- Reverse lookup: find the Rosetta equivalent of a Biotite function
• translate_rosetta_script_to_biotite -- Translate entire RosettaScripts XML or PyRosetta code to Biotite Python. Design/optimization operations are flagged as Rosetta-only.
• Fuzzy search with keyword aliases ("contacts", "binding energy", "surface area", "align", etc.)

Improved: XML to PyRosetta translator

• 37 element types supported (was 6): 11 movers, 9 filters, 10 selectors, 7 task operations
• Full attribute handling: repeats, disable_design, cartesian, tolerance, threshold, distance, and more
• Child element support: MoveMap (with Span), Reweight, ScoreFunction
• Reports unrecognized elements so you know what needs manual work

Improved: Help and documentation

• get_rosetta_help now accepts any topic: movers by name ("FastRelax"), concepts ("constraints", "docking"), or score functions ("ref2015") -- auto-fetches live docs from rosettacommons.org
• search_rosetta_web_docs fallback: when DuckDuckGo is rate-limited, probes direct Rosetta docs URLs
• get_cached_docs auto-caches: no need to call cache_cli_docs first
• Expanded static help for score_functions, movers, filters, xml, and parameters

Improved: Scoring

• pyrosetta_score: new per_residue option returns per-residue energy breakdown
• scorefxn parameter now works (was ignored in v1.1.8)
• Proper error messages for missing files instead of silent {}

Improved: Validation

• validate_xml: new validate_against_schema option checks element names against the Rosetta XSD schema (catches typos like FastRleax)

MCP spec compliance fixes

• tools/call responses now use correct { content: [{ type: "text", text }] } format
• Tool errors return isError: true (not JSON-RPC errors)
• Standard JSON-RPC error codes (-32601, -32700, -32603)
• Removed false resources capability advertisement

Security fixes

• User input no longer interpolated into Python code (uses env vars / stdin)
• Temp files written to os.tmpdir() (not module directory)

Cleanup

• Removed 3 redundant tools: list_functions (merged into get_rosetta_info), search_pyrosetta_wheels, cache_cli_docs (auto-cache in get_cached_docs)
• Removed hardcoded personal paths
• Fixed shadowed variables, async anti-patterns, dead code
• 18 tools (was 21), all with improved agent-oriented descriptions

---

Example: asking a naive question

This is what makes the MCP server powerful -- an AI agent can answer domain questions by calling the right tools automatically:

User asks in Cursor: "How do I relax my protein and what's the Biotite equivalent?"

The agent calls two MCP tools behind the scenes:

1. get_rosetta_help("FastRelax") returns 6000+ chars of live documentation: > FastRelax performs all-atom relaxation using the FastRelax protocol. Parameters include scorefxn, repeats, cartesian, disable_design, MoveMap configuration...

2. rosetta_to_biotite("FastRelax") returns: ``json { "found": true, "results": [{ "rosetta": { "name": "FastRelax", "example": ["relax = FastRelax()", "relax.set_scorefxn(get_score_function('ref2015'))", "relax.apply(pose)"] }, "biotite": null, "equivalence": "none_from_biotite", "notes": "Biotite does NOT perform structure optimization. These are Rosetta-specific capabilities." }] } ``

The agent synthesizes: "FastRelax is Rosetta's all-atom relaxation protocol. Here's how to use it... Note: Biotite is analysis-only and has no equivalent -- you need PyRosetta for structure optimization."

Without the MCP, the agent would guess from training data and likely get parameter names or API signatures wrong.

---

What you get (18 tools)

Discovery & Help

| Tool | Description | |------|-------------| | get_rosetta_info | All available score functions, movers, filters, selectors, parameters | | get_rosetta_help | Help for any topic -- accepts mover names, concepts, or score functions | | pyrosetta_introspect | Live PyRosetta API search with docs and signatures |

Documentation

| Tool | Description | |------|-------------| | search_rosetta_web_docs | Search rosettacommons.org documentation | | get_rosetta_web_doc | Fetch and read a specific docs page | | get_cached_docs | Search cached CLI help (auto-caches on first use) |

Execution & Scoring

| Tool | Description | |------|-------------| | run_rosetta_scripts | Run a RosettaScripts XML protocol on a PDB | | pyrosetta_score | Score a PDB with optional per-residue breakdown |

Translation

| Tool | Description | |------|-------------| | xml_to_pyrosetta | XML to PyRosetta Python (37 element types) | | rosetta_to_biotite | Find Biotite equivalent of a Rosetta function | | biotite_to_rosetta | Find Rosetta equivalent of a Biotite function | | translate_rosetta_script_to_biotite | Translate full scripts from Rosetta to Biotite |

Validation & Schema

| Tool | Description | |------|-------------| | validate_xml | Check XML syntax + optional schema validation | | rosetta_scripts_schema | Generate XSD schema and extract element names |

Environment

| Tool | Description | |------|-------------| | python_env_info | Python version and installed packages | | check_pyrosetta | Verify PyRosetta is available | | install_pyrosetta_installer | Auto-install PyRosetta (10-30 min) | | find_rosetta_scripts | Locate the rosetta_scripts binary |

---

Quick start

1. Install from npm

npm install -g rosetta-mcp-server

2. Set up Python environment

# Create a venv with PyRosetta and Biotite
uv venv ~/.venvs/rosetta-mcp
~/.venvs/rosetta-mcp/bin/pip install pyrosetta-installer biotite
~/.venvs/rosetta-mcp/bin/python -c "import pyrosetta_installer as I; I.install_pyrosetta()"

Or skip this step -- PyRosetta auto-installs on first use (takes 10-30 min).

3. Configure your MCP client

Cursor (~/.cursor/mcp.json): ``json { "mcpServers": { "rosetta": { "command": "rosetta-mcp-server", "args": [], "env": { "ROSETTA_BIN": "/path/to/rosetta_scripts.default.macosclangrelease", "PYTHON_BIN": "/path/to/.venvs/rosetta-mcp/bin/python" } } } } ``

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json): ``json { "mcpServers": { "rosetta": { "command": "rosetta-mcp-server", "env": { "ROSETTA_BIN": "/path/to/rosetta_scripts.default.macosclangrelease", "PYTHON_BIN": "/path/to/.venvs/rosetta-mcp/bin/python" } } } } ``

Environment variables: | Variable | Required | Description | |----------|----------|-------------| | ROSETTA_BIN | No | Path to rosetta_scripts binary or its directory. If not set, searches common paths and PATH. | | PYTHON_BIN | No | Python interpreter with PyRosetta/Biotite. Defaults to python3. | | MCP_DEBUG | No | Set to 1 for debug logging to stderr. |

4. Restart your editor

Open Settings -> MCP. The "rosetta" server should appear green with 18 tools.

---

XML to PyRosetta translation example

Input XML: ``xml <ROSETTASCRIPTS> <SCOREFXNS> <ScoreFunction name="ref" weights="ref2015"/> </SCOREFXNS> <RESIDUE_SELECTORS> <Chain name="chainA" chains="A"/> </RESIDUE_SELECTORS> <MOVERS> <FastRelax name="relax" scorefxn="ref" repeats="5" cartesian="true"/> </MOVERS> <PROTOCOLS> <Add mover="relax"/> </PROTOCOLS> </ROSETTASCRIPTS> ``

Generated PyRosetta code: ```python import pyrosetta from pyrosetta import pose_from_pdb from pyrosetta.rosetta.core.scoring import get_score_function from pyrosetta.rosetta.core.select.residue_selector import from pyrosetta.rosetta.protocols.relax import

pyrosetta.init("-mute all")

pose = pose_from_pdb("your_protein.pdb")

Residue Selectors

chainSelector = ChainSelector() chainSelector.set_chain_strings("A")

Movers

fastRelax = FastRelax() fastRelax.set_scorefxn(get_score_function("ref")) fastRelax.set_default_repeats(5) fastRelax.cartesian(True)

sfxn = get_score_function("ref2015")

Apply movers

fastRelax.apply(pose)

pose.dump_pdb("output.pdb") score = pose.energies().total_energy() print(f"Final score: {score}") ```

---

Rosetta <-> Biotite mapping coverage

| Category | Rosetta | Biotite | Equivalence | |----------|---------|---------|-------------| | Structure I/O | pose_from_pdb | PDBFile.read | Full | | Structure I/O | pose.dump_pdb | PDBFile.write | Full | | Structure I/O | pose_from_file (CIF) | CIFFile.read | Full | | Surface Analysis | SasaMetric | biotite.structure.sasa | Full | | Alignment | SuperimposeMover | biotite.structure.superimpose | Full | | RMSD | all_atom_rmsd | biotite.structure.rmsd | Full | | Secondary Structure | DsspMover | annotate_sse | Partial | | Sequence | pose.sequence() | get_residues | Full | | Distance | AtomPairConstraint | biotite.structure.distance | Full | | Angles | pose.phi/psi/omega | biotite.structure.dihedral | Full | | Interface | InterfaceAnalyzerMover | sasa + selection | Partial | | Database | rcsb.pose_from_rcsb | rcsb.fetch | Full | | Selection | ChainSelector etc. | numpy boolean indexing | Full | | Contacts | distance matrices | CellList | Partial | | Ramachandran | pose.phi/psi | dihedral_backbone | Partial | | H-bonds | HBondSet | biotite.structure.hbond | Partial | | B-factors | pdb_info().bfactor | AtomArray.b_factor | Full | | Center of Mass | center_of_mass | mass_center | Full | | Scoring | ScoreFunction | None | Rosetta only | | Optimization | FastRelax | None | Rosetta only | | Design | FastDesign | None | Rosetta only |

---

Troubleshooting

• Server shows red in Cursor: Restart Cursor. Use absolute path in config (e.g., /opt/homebrew/bin/rosetta-mcp-server). Ensure Node 14+ and Python 3.8+.
• run_rosetta_scripts fails: Verify ROSETTA_BIN points to a valid binary. Try "$ROSETTA_BIN" -help.
• PyRosetta tools say "not available": Install via pip install pyrosetta-installer then run the installer, or let the MCP server auto-install on first use.
• Biotite tools return no results: Install Biotite in the same Python env: pip install biotite
• get_rosetta_help returns "No detailed help": Try the exact Rosetta class name (e.g., "FastRelax" not "relax"). The tool resolves common aliases but may miss unusual names.

Verify from the command line

# Check version
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | rosetta-mcp-server 2>/dev/null | python3 -c "import sys,json; print(json.loads(sys.stdin.readline())['result']['serverInfo'])"

# List all tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | rosetta-mcp-server 2>/dev/null | python3 -c "import sys,json; [print(t['name']) for t in json.loads(sys.stdin.readline())['result']['tools']]"

Development

rosetta-mcp-server/
├── rosetta_mcp_wrapper.js   # Node MCP server (protocol + all 18 tools)
├── rosetta_mcp_server.py    # Python helper (static Rosetta data)
├── install_pyrosetta.js     # Standalone PyRosetta installer
├── package.json             # npm package config
└── README.md

License and attribution

• MIT for this repository
• Rosetta/PyRosetta: see RosettaCommons licenses; commercial use requires the appropriate license
• Biotite: BSD 3-Clause license