shelx-mcp

An MCP server that wraps the SHELX console crystallography programs so an LLM can build .ins instruction files, run structure solutions and refinements, and read the results back — all from a chat interface.

It ships with the authoritative SHELXL instruction reference and the SHELXS / SHELXD / SHELXE solution-program references bundled offline, so the model can look up what any command or solution keyword does without leaving the conversation.

---

What it does

The server exposes 11 tools split into two coverage areas:

• Refinement (SHELXL) — the cards that build and refine a model.
• Structure solution (SHELXS / SHELXD / SHELXE) — the keywords that find a structure in the first place.

Tool	Coverage	Purpose
run_shelx	both	Execute any allowed SHELX program on supplied input files.
solve	solution	Run structure solution (SHELXS direct methods, or SHELXT dual-space).
refine	refinement	Run least-squares refinement with SHELXL (or CGLS via SHELXT).
list_commands	refinement	List every SHELXL instruction the server understands.
command_help	refinement	Full signature + description for one instruction (e.g. ANIS, L.S.).
search_commands	refinement	Free-text search across instruction names and descriptions.
list_solution_keywords	solution	List SHELXS/SHELXD .ins cards or SHELXE command-line options.
solution_help	solution	Full signature + description for one solution keyword (e.g. TREF, -aN).
validate_ins	refinement	Check an .ins file for the required SHELXL header cards.
analyze_results	both	Extract R1, wR2, GooF (S), max shift/esd, atom count and warnings.
shelx_info	both	Report the configured SHELX directory and available programs.

Refinement vs. solution coverage. SHELXL refines a model you already have; SHELXS/SHELXD/SHELXE find the model from diffraction data. Use list_commands / command_help / search_commands for refinement cards, and list_solution_keywords / solution_help for solution keywords. SHELXT and SHELXC ship as tutorials rather than keyword lists, so they are not included as references (but they can still be run via run_shelx / solve).

How SHELX is driven

SHELX programs are console tools driven by a basename: shelxl name reads name.ins (and name.hkl when an HKLF instruction is present) and writes name.res, name.lst, and optionally name.cif / name.fcf. This server writes the input files to a (throw-away) working directory, runs the executable, and returns the generated files as text.

---

Requirements

• Python >= 3.10 (the project uses uv, which fetches its own interpreter if needed).
• The SHELX executables installed locally (download from https://shelx.uni-goettingen.de/ or your site licence). On the author's machine they live in C:/Users/kuzmi/AppData/Local/shelx64/.
• uv for dependency / environment management.

---

Installation

git clone https://github.com/stge4code/shelx-mcp.git
cd shelx-mcp
uv sync                 # creates .venv and installs mcp + python-dotenv
uv sync --extra test    # additionally installs pytest for the test suite

Configure the SHELX location

Copy the template and point SHELX_DIRECTORY at the folder that contains the *.exe files:

cp .env.example .env
# then edit .env:
# SHELX_DIRECTORY=C:/path/to/shelx64

.env is git-ignored (it contains a machine-specific path). Only .env.example is committed.

Run the server

The server speaks MCP over stdio, so you normally do not launch it by hand — your agent does. To smoke-test it manually:

uv run shelx-mcp                      # runs the stdio server
uv run python -m shelx_mcp.server    # equivalent

Verify the wiring (and that SHELX was found) before connecting an agent:

uv run python -c "import shelx_mcp.server as s; print(s.shelx_info())"

---

Connecting an agent

All of the configurations below launch the server with:

uv --directory <repo> run shelx-mcp

Replace <repo> with the absolute path to this checkout (e.g. X:/DATA/Git/shelx-mcp). The .env file inside the repo is picked up automatically at startup. Every client uses the same command / args pair; only the config file location and key names differ.

Agent	Config file	Key	Example
Crush	crush.json (project root or ~/.config/crush/)	mcp ("type": "stdio")	examples/crush.json
OpenCode	~/.config/opencode/opencode.jsonc	mcpServers	examples/opencode.jsonc
Claude Desktop	claude_desktop_config.json	mcpServers	examples/claude_desktop.json
VS Code / Copilot	.vscode/mcp.json	servers ("type": "stdio")	examples/vscode_mcp.json
Zed	~/.config/zed/settings.json	context_servers	examples/zed.json
Cursor	.cursor/mcp.json	mcpServers	examples/cursor.json
Cline	cline_mcp_settings.json	mcpServers	examples/cline.json

Copy the matching example into the agent's config location (or merge its server block into an existing config) and restart the agent. The shelx server then appears in the MCP list with its eleven tools available in any conversation.

For Crush specifically, the block looks like (note the mcp key and the required type field, unlike the mcpServers key used by Claude/Cursor/Cline):

{
  "mcp": {
    "shelx": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "X:/DATA/Git/shelx-mcp", "run", "shelx-mcp"]
    }
  }
}

uv must be on the agent's PATH. If it is not, replace "uv" with the absolute path to uv.exe (e.g. C:/Users/kuzmi/.local/bin/uv.exe).

Skills

A reusable agent skill that teaches the workflow (look up instructions, validate, solve, refine, analyze) lives at skills/shelx/SKILL.md. To install it for Crush, copy the folder into your skills directory:

mkdir -p ~/.config/crush/skills/shelx
cp -r skills/shelx/* ~/.config/crush/skills/shelx/

Other agents that support markdown skills can load the same file. The skill keeps the SHELX card order and the solve→refine→analyze loop consistent across sessions.

---

Typical workflow

1. Look up a command — refinement card: command_help("ANIS") or search_commands("rigid group"); solution keyword: list_solution_keywords("shelxs") then solution_help("shelxs", "TREF").
2. Build the model — paste or generate an .ins file, then validate_ins(...) to confirm the header cards.
3. Solve / refine — call solve(ins, hkl) (SHELXS/SHELXT) or refine(ins, hkl) (SHELXL).
4. Read the outcome — analyze_results(lst=..., res=...) returns the R-factors, GooF and any warnings; the full .lst / .res are returned inline by the run tools for deeper inspection.

---

Tool reference

run_shelx(program, ins, hkl=None, basename="shelx_job", workdir=None, timeout=120, return_output=True)

Run any allowed SHELX program on the supplied .ins (and optional .hkl) text. Returns the program output, return code, and (when return_output is true) the generated .res / .lst / .cif files. program must be one of shelxs, shelxl, shelxt, shelxc, shelxd, shelxe, ciftab.

solve(ins, hkl=None, program="shelxs", basename="solve", timeout=120)

Run structure solution. program is shelxs (direct methods) or shelxt (dual-space). Requires an .ins set up for solution (TITL, CELL, ZERR, LATT, SYMM, SFAC, UNIT, plus e.g. TREF/FMAP, and HKLF/END) and the corresponding .hkl data.

refine(ins, hkl=None, program="shelxl", basename="refine", timeout=300)

Run least-squares refinement. Requires a complete .ins (with L.S./CGLS and HKLF) and the .hkl data. Returns the .lst summary and refined .res.

list_commands()

Return every SHELXL instruction name the server knows (alphabetical).

command_help(name)

Return the signature and full description for one SHELXL instruction (e.g. command_help("ANIS"), command_help("L.S.")).

search_commands(query, limit=10)

Free-text search across instruction names, signatures, descriptions, related cards and example lines.

list_solution_keywords(program)

List the .ins cards (SHELXS/SHELXD) or command-line options (SHELXE) for program ∈ {shelxs, shelxd, shelxe}.

solution_help(program, keyword)

Return the signature and full description for one solution keyword. For SHELXS/SHELXD use the card name (e.g. solution_help("shelxs", "TREF")); for SHELXE use the option including its dash and placeholder (e.g. solution_help("shelxe", "-aN")). SHELXE options are case-sensitive.

validate_ins(ins)

Check an .ins file for the required SHELXL header cards (TITL, CELL, ZERR, LATT, SYMM, SFAC, UNIT, HKLF, END) and a few common mistakes (e.g. SYMM is not required for P1/P-1; UNIT must precede HKLF).

analyze_results(lst=None, res=None)

Summarise refinement metrics: R1, wR2, GooF (S), max shift/esd, atom count and any warning lines from the .lst / .res text.

shelx_info()

Report the configured SHELX_DIRECTORY and which SHELX programs are present.

---

Bundled reference data (offline)

The server does not call the web at runtime. It parses these bundled HTML files (from https://shelx.uni-goettingen.de/) at startup:

File	Programs covered
data/shelxl_reference.html	SHELXL refinement instructions
data/shelxs_keywords.html	SHELXS .ins solution cards
data/shelxd_sm_keywords.html	SHELXD .ins solution cards
data/shelxe_keywords.html	SHELXE command-line options

To refresh the references, re-download the corresponding pages and replace the files in src/shelx_mcp/data/ (they are included in the wheel via force-include in pyproject.toml).

---

Project layout

shelx-mcp/
├── .env.example                 # template for SHELX_DIRECTORY
├── pyproject.toml               # uv / hatchling project metadata
├── examples/
│   ├── crush.json               # Crush MCP config
│   ├── opencode.jsonc           # OpenCode MCP config
│   ├── claude_desktop.json      # Claude Desktop config
│   ├── vscode_mcp.json          # VS Code / Copilot (.vscode/mcp.json)
│   ├── zed.json                 # Zed context_servers
│   ├── cursor.json              # Cursor .cursor/mcp.json
│   └── cline.json               # Cline settings
├── skills/
│   └── shelx/
│       └── SKILL.md             # agent skill: SHELX solve/refine workflow
├── src/shelx_mcp/
│   ├── server.py                # FastMCP server + tools
│   ├── runner.py                # safe subprocess execution of SHELX
│   ├── reference.py             # parses the bundled SHELXL instruction HTML
│   ├── solution_ref.py          # parses the bundled SHELXS/SHELXD/SHELXE references
│   ├── analysis.py              # extracts R1/wR2/GooF/atoms/warnings
│   └── data/
│       ├── shelxl_reference.html    # bundled, offline SHELXL manual
│       ├── shelxs_keywords.html     # SHELXS .ins cards
│       ├── shelxd_sm_keywords.html  # SHELXD .ins cards
│       └── shelxe_keywords.html     # SHELXE command-line options
└── tests/
    └── test_server.py

---

Development

uv sync --extra test
uv run pytest -q                 # run the test suite (no real SHELX needed)
uvx ruff@0.11.0 check src tests  # lint

Tests cover reference/solution parsing, output analysis, validate_ins, the server tools, and (when SHELX_DIRECTORY is configured) an end-to-end SHELX run.

---

Security notes

• Only the programs in ALLOWED_PROGRAMS (shelxs, shelxl, shelxt, shelxc, shelxd, shelxe, ciftab) can be executed — the program argument cannot be abused to run arbitrary commands.
• The basename is restricted to [A-Za-z0-9_.-] and the values . / .. are rejected, so it cannot escape the working directory.
• Extra input files must be bare names with no directory components.
• Input files are written to a temporary directory that is removed after the run (unless you pass workdir explicitly), so the server never writes into your repo.