pdb2reaction-mcp

name: pdb2reaction-mcp description: How to drive `pdb2reaction` from an MCP-speaking agent (Claude Desktop / Claude Code / Cursor / Codeium / custom Python or TypeScript MCP SDK clients) via the bundled `pdb2reaction-mcp` (alias `p2r-mcp`) server. Lists the 18 MCP tools (one per CLI subcommand) and the shared `SubcmdResult` schema. TRIGGER on questions about MCP setup, agent integration, tool names, return-value shape, or "how does an agent invoke pdb2reaction". SKIP for direct CLI usage — that's `pdb2reaction-cli`.

pdb2reaction MCP server

pdb2reaction-mcp exposes every CLI subcommand as an MCP tool over stdio JSON-RPC. Any MCP client can drive the full reaction-path pipeline without spawning shell processes manually.

Install + register

pip install "pdb2reaction[mcp]"   # adds the `mcp[cli]` extra

This registers two console scripts: pdb2reaction-mcp and p2r-mcp (alias).

Drop the snippet below into your client's MCP config file:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor — ~/.cursor/mcp.json
Other MCP clients — consult the client's own MCP-server docs

{
  "mcpServers": {
    "pdb2reaction": {
      "command": "pdb2reaction-mcp",
      "args": []
    }
  }
}

See examples/mcp_client_config.json for a full sample with explicit PATH / CUDA_VISIBLE_DEVICES env-var overrides.

18 tools (1 per CLI subcommand)

Stage runners

MCP tool	wraps	purpose
`optimize_geometry`	`pdb2reaction opt`	Optimise one structure
`find_transition_state`	`pdb2reaction tsopt`	TS search (RS-I-RFO / Dimer / TRIM / RS-P-RFO)
`run_irc`	`pdb2reaction irc`	IRC integration from a TS geometry
`compute_frequencies`	`pdb2reaction freq`	Vibrational analysis + thermochemistry
`run_single_point`	`pdb2reaction sp`	Single-point MLIP energy + forces (+optional Hessian)

Scans / paths / pipeline

MCP tool	wraps	purpose
`scan_1d` / `scan_2d` / `scan_3d`	`pdb2reaction scan{,2d,3d}`	Restraint-driven distance scans
`optimize_path`	`pdb2reaction path-opt`	Two-endpoint MEP optimisation
`search_paths`	`pdb2reaction path-search`	Recursive reaction-pathway search
`run_full_pipeline`	`pdb2reaction all`	End-to-end (extract → MEP → TS → IRC → freq → DFT)
`run_single_point_dft`	`pdb2reaction dft`	Single-point DFT via gpu4pyscf

Structure / I/O helpers

MCP tool	wraps	purpose
`extract_active_site`	`pdb2reaction extract`	Cut a sphere around a ligand
`add_element_info`	`pdb2reaction add-elem-info`	Repair PDB element columns
`fix_altloc`	`pdb2reaction fix-altloc`	Resolve PDB alternate locations
`plot_trajectory`	`pdb2reaction trj2fig`	Energy profile PNG / SVG / PDF / HTML / CSV
`plot_energy_diagram`	`pdb2reaction energy-diagram`	Categorical energy diagram
`detect_bond_changes`	`pdb2reaction bond-summary`	Bond-change diff between two PDBs

`SubcmdResult` return schema

Every tool returns the same structured dict so the calling agent can dispatch on status without parsing stderr:

{
    "schema_version": "1.0",         # pin to MCP_SUBCMD_RESULT_SCHEMA_VERSION
    "status": "ok" | "failed" | "summary_missing" | "summary_parse_error",
    "exit_code": int,                # subprocess exit code
    "out_dir": str | None,           # working directory the CLI wrote to
    "summary": dict,                 # parsed summary.json (CLI output schema)
    "stderr_tail": str,              # last ~60 lines of stderr
    "stdout_tail": str,              # last ~60 lines of stdout
    "hint": str | None,              # parsed `; recover: <hint>` suffix
    "argv": list[str],               # full argv that was executed (reproducible)
}

A failed subcommand additionally surfaces a structured exception envelope inside summary:

error_class_chain — list of class names walking the MRO (e.g. ["CudaOutOfMemoryError", "RuntimeError", "Exception"])
error_module — module path of the originating exception class
error_label — high-level CLI stage label (e.g. "IRC", "optimization", "frequency analysis", "path optimization", fallback "UnhandledError")

so an MCP client can pattern-match on the hierarchy instead of substring-matching stderr_tail.

`find_transition_state` opt-mode kwarg

Beyond the default RS-I-RFO, find_transition_state accepts:

opt_mode="trim" — Helgaker trust-region image-minimisation TS opt
opt_mode="rsprfo" — Banerjee restricted-step P-RFO TS opt

Sandbox / safety notes

The MCP server inherits the calling environment's PATH, conda env, and CUDA setup. Long-running tools (opt / tsopt / irc) launch the pdb2reaction CLI in a subprocess — set timeout_seconds on each call to bound runaway computations.
Output files land under the out_dir kwarg (defaults to a unique tempfile.mkdtemp("p2r_mcp_<subcmd>_…") so concurrent agent calls don't collide).
The server does not modify ~/.bashrc / login env, install software, or write outside out_dir. All MLIP weights / PDB inputs must already exist on disk.