Catalysis Hub MCP Server Surface Reaction Data

Overview

The Catalysis Hub MCP Server exposes computational catalysis and surface reaction data through a Model Context Protocol (MCP)–compatible service. It lets researchers and tools (including LLMs and model-driven pipelines) query and retrieve structured information about reaction pathways, adsorbate geometries, electronic energies, and metadata from the Catalysis Hub dataset. By packaging scientific context as programmatic tools, the server helps automate literature-style lookups, feed LLM agents with domain facts, and accelerate data-driven workflows in heterogeneous catalysis and surface science.

This server is useful when you need reproducible, machine-readable access to catalysis datasets: search for reactions by adsorbate or surface, fetch computed structures and energy components, and integrate those results into downstream analysis, visualization, or model-conditioning steps. The MCP interface is designed so LLM agents and other model consumers can request contextual data on demand and use it as part of a larger reasoning chain.

Features

• REST API that returns structured reaction and structure data for catalysis research
• Search and filtering by adsorbate, surface, reaction type, and energy ranges
• Retrieval of computed geometries (POSCAR/CIF-like), total/adsorption energies, and calculation metadata
• MCP-compatible endpoints so generative models and agent frameworks can request context tools
• Lightweight, deployable as a Python app or Docker container
• Extensible configuration for backing databases or remote data sources

Installation / Configuration

Clone the repository, create a virtual environment, install dependencies, and run the server. Example commands:

# Clone repo
git clone https://github.com/QuentinCody/catalysishub-mcp-server.git
cd catalysishub-mcp-server

# Create venv and install
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Start server (example using uvicorn/FastAPI)
uvicorn app.main:app --host 0.0.0.0 --port 8080

Environment variables (example .env):

DATABASE_URL=postgresql://user:pass@localhost:5432/catalysis
MCP_PORT=8080
SECRET_KEY=replace-with-secure-value
LOG_LEVEL=info

Docker usage:

# Build
docker build -t catalysis-mcp-server .

# Run (example)
docker run -e DATABASE_URL=$DATABASE_URL -p 8080:8080 catalysis-mcp-server

Adjust DATABASE_URL to point to a local or managed database containing the Catalysis Hub dataset, or configure the server to use a remote API endpoint if available.

Available Resources

Common REST endpoints (examples — check running server for exact routes):

Sample query parameters for /search:

• q: free-text search
• adsorbate: chemical formula (e.g., CO, O2)
• surface: surface label (e.g., Pt(111))
• energy_min / energy_max: filter by total or adsorption energy (eV)
• limit / offset: pagination

Example: retrieve reaction record by id (curl)

curl -sS "http://localhost:8080/reaction/12345" | jq .

Example: search by adsorbate and energy range

curl -sS "http://localhost:8080/search?adsorbate=CO&surface=Pt(111)&energy_max=-0.5&limit=20" | jq .

MCP tool invocation (example payload):

POST /mcp/tool
{
  "tool": "catalysis_search",
  "args": {"adsorbate": "CO", "surface": "Pt(111)", "limit": 5}
}

The server responds with JSON containing structured entries suitable for model consumption (summaries, key numeric values, and links to geometry files).

Use Cases

• Integrate with an LLM agent: expose the server as an MCP tool so an LLM can “look up” computed energies and geometries during a reasoning session (e.g., when drafting a methods section or proposing reaction mechanisms).
• Reproducible analysis pipelines: programmatically fetch reaction datasets for automated post-processing — e.g., collecting adsorption energies for bar plots or ML feature engineering.
• Interactive dashboards and visualization: back a web UI that lists reactions, shows atomic structures, and plots energy profiles; use the API to stream data to plotting components.
• Batch retrieval for ML training: download large subsets of structures and labels (adsorption energy, computed barriers) for model training while keeping provenance metadata intact.
• Cross-referencing literature: combine server responses with external identifiers (DOI, dataset IDs) to generate citation-ready provenance for computations.

Getting Started Tips

• Inspect /health and auto-generated API docs (if available) to confirm endpoints and parameter names.
• Start with small queries (limit=10) to understand response schemas before writing large data pulls.
• Store geometry files locally or in a data lake if you plan batch processing; use the provided metadata fields for provenance.
• If integrating with LLMs, prefer the MCP POST /mcp/tool pattern to ensure model tooling frameworks can invoke search and retrieval seamlessly.

For implementation details, examples, and contribution guidelines, see the project repository: https://github.com/QuentinCody/catalysishub-mcp-server.