Ypotheto Computational Chemistry MCP Server (ypotheto-compchem-mcp)

Ypotheto Computational Chemistry MCP Server (ypotheto-compchem-mcp)

An MCP (Model Context Protocol) server that provides natural language interfaces and AI assistants with access to computational chemistry, cheminformatics, and molecular modeling tools.

Powered by RDKit, PySCF, and the Atomic Simulation Environment (ASE).

Features

• Molecule Builder: Convert SMILES strings to 3D optimized geometries (MMFF94 or UFF) and render 2D layout diagrams (SVG).
• Cheminformatics: Calculate molecular descriptors (Molecular Weight, LogP, TPSA, Rotatable Bonds) and evaluate compliance with Lipinski's Rule of Five.
• Electronic Structure Theory: Run Hartree-Fock (HF) and Density Functional Theory (DFT) single-point calculations using PySCF. Retrieve total energies, dipole moments, HOMO/LUMO band gaps, and Mulliken atomic charges.
• Geometry Optimization: Relax molecular structures to energy minima using ASE's LBFGS optimizer coupled with PySCF or RDKit force fields.
• Vibrational Spectroscopy: Run harmonic vibrational analysis to determine normal modes, frequencies, Zero-Point Energy (ZPE), and thermochemical corrections (Enthalpy, Entropy, Gibbs energy). Simulates IR intensities and generates Lorentzian line-broadened IR spectra plots.
• Molecular Dynamics (MD): Propagate NVE (VelocityVerlet) or NVT (Langevin) trajectories. Saves multi-frame XYZ files and renders energy/temperature conservation plots.
• Asynchronous Job Manager: Long-running calculations (like DFT optimizations or dynamics) run in background threads with progress updates, avoiding client timeouts.
• File-First Artifacts: Visual outputs (plots, diagrams) and heavy coordinate files (SDF, XYZ, PDB) are written to a local data directory and returned as public URLs instead of bloating the LLM's chat context.

Local Development & Setup

This project uses uv for lightning-fast virtualenv and dependency management.

1. Prerequisites

• Python >= 3.11
• Windows, macOS, or Linux.
• Note: PySCF requires C compilation libraries. If running natively on Windows without WSL/Conda, PySCF tools will automatically report as unavailable, but the RDKit builder, descriptors, and forcefield-based optimizations/dynamics/vibrations will still run perfectly.

2. Install Dependencies

# Clone the repository
git clone <repo-url>
cd compchem-mcp

# Create a virtual environment and install in editable mode
uv venv
uv pip install -e .

# (Optional) Install pytest to run tests
uv pip install pytest

3. Run the Tests

.\.venv\Scripts\python.exe -m pytest

4. Run the Server

The server supports two transport mechanisms: STDIO (default) for desktop client plugins and HTTP (SSE/Streamable HTTP) for hosted web apps.

# Start STDIO mode
.\.venv\Scripts\python.exe -m ypotheto_compchem_mcp --transport stdio

# Start HTTP mode
.\.venv\Scripts\python.exe -m ypotheto_compchem_mcp --transport http --port 8348

Running in Docker

To run full PySCF quantum calculations natively on Windows or deploy to DigitalOcean, compile and run inside Docker:

# Build the Docker image
docker build -t ypotheto-compchem-mcp .

# Run the container (binds workspace data to a local directory)
docker run -p 8348:8348 -v C:/data/compchem:/data ypotheto-compchem-mcp

Client Integration Configuration

1. Claude Desktop (STDIO)

To register the server directly with Claude Desktop, add it to your claude_desktop_config.json configuration file:

{
  "mcpServers": {
    "ypotheto-compchem": {
      "command": "python",
      "args": [
        "-m",
        "ypotheto_compchem_mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "COMPCHEM_DATA_DIR": "C:/Users/<your-user>/.compchem-mcp"
      }
    }
  }
}

2. ypotheto-core / SSE Web Client

To connect a remote client over streamable HTTP with Bearer token authentication:

1. Start the server:

   COMPCHEM_API_TOKEN="secret_api_token" python -m ypotheto_compchem_mcp --transport http --port 8348
   

2. Configure your client (e.g. StreamableHttpMcpClient) to connect to:
   • URL: http://localhost:8348/mcp
   • Headers: Authorization: Bearer secret_api_token

Environment Variables

Tool Catalog Overview