ChemGraph¶
ChemGraph turns natural-language requests into computational chemistry and materials-science workflows. It combines LangGraph and LangChain agents with ASE, RDKit, MCP servers, and pluggable execution backends.
Use ChemGraph through the command line, Python, a Streamlit interface, or as an MCP server. Start locally with the lightweight EMT calculator, then opt into larger models, external simulation programs, or distributed execution when a workflow needs them.
Review generated calculations
ChemGraph can launch calculations and write files. Check generated inputs, calculator settings, convergence, units, and scientific conclusions before relying on a result.
First run¶
Install ChemGraph in a virtual environment:
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install chemgraph
Set one model-provider credential, then check the installation and run a query:
export OPENAI_API_KEY="..."
chemgraph run --check-keys
chemgraph run -q "What is the SMILES string for aspirin?"
The quickstart adds a first EMT calculation and explains where ChemGraph writes artifacts. Argonne users can follow the same guide with an Argo or ALCF-hosted model.
Find the right guide¶
| Goal | Guide |
|---|---|
| Install core or optional dependencies | Installation |
| Configure a model provider | Models and authentication |
| Learn CLI commands and saved sessions | Command-line interface |
| Select an agent architecture | Workflows |
| Choose a chemistry calculator | Calculators |
| Embed ChemGraph in Python | Python API |
| Use a browser interface | Streamlit interface |
| Connect MCP clients and servers | MCP servers |
| Run with containers | Docker |
| Deploy Streamlit and MCP to a cluster | Kubernetes |
| Scale across execution backends | HPC and Academy |
| Evaluate models with structured ground truth | Evaluation and the ChemGraph Leaderboard |
| Diagnose a failed first run | Troubleshooting |
Support levels¶
The single-agent CLI/Python path, core ASE tools, EMT, MACE, and the general MCP server are the normal starting points. Optional integrations require their documented extras or external programs. Codex subscription support requires its optional SDK and a ChatGPT login; see Codex subscription. Site-specific HPC servers, gRASPA workflows, docking, XANES, and some distributed backends are advanced or experimental; validate them in your own environment before production use.