ChemGraph is an agent framework for computational chemistry and materials science. It connects natural-language requests to molecular construction, simulation, analysis, and reporting tools built with LangGraph, ASE, RDKit, and the Model Context Protocol (MCP).
Use it from the command line, Python, a Streamlit web interface, or as an MCP server. Start with local ASE calculators such as EMT and MACE, then add TBLite, UMA, docking, XANES, retrieval, or distributed execution on systems such as ALCF Polaris and Aurora as your workflow grows.
Documentation · News · Papers and citations · Model leaderboard
Review results. ChemGraph can launch calculations, run commands, and write files. Review generated inputs, calculator settings, convergence, units, and scientific conclusions before relying on a result.
ChemGraph requires Python 3.11 or newer. To use the command-line application,
install it with uv, which creates an
isolated environment and puts chemgraph on your PATH:
uv tool install chemgraphTo use ChemGraph from Python or a notebook, install it into a virtual environment instead (this also provides the CLI):
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install chemgraph # or: uv venv && uv pip install chemgraphChoose one model provider and set only the credential it needs. The default
model is gpt-4o-mini.
| Provider | Setup | Example model |
|---|---|---|
| OpenAI | export OPENAI_API_KEY="..." |
gpt-4o-mini |
| Anthropic | export ANTHROPIC_API_KEY="..." |
claude-3-5-haiku-20241022 |
export GEMINI_API_KEY="..." |
gemini-2.5-flash |
|
| Groq | export GROQ_API_KEY="..." |
groq:<model-id> |
| Argo (Argonne) | export ARGO_USER="<anl-username>" |
argo:gpt-4o |
| ALCF inference endpoints | export ALCF_ACCESS_TOKEN="..." |
Use chemgraph models |
| Ollama | Start Ollama locally; no API key | llama3.2 |
Check the setup, then run a lookup and a small calculation:
chemgraph run --check-keys
chemgraph run -q "What is the SMILES string for aspirin?"
chemgraph run --output last_message \
-q "Build water from SMILES O, optimize it with EMT, and report the final energy."Both queries call the selected model; the aspirin lookup also uses PubChem.
EMT needs no downloaded weights, which makes it a good first calculation.
Structures, trajectories, JSON results, and reports are written to a session
directory under cg_logs/ (set CHEMGRAPH_LOG_DIR to change it).
Next steps: the quickstart guide, models and authentication, and installation options for conda and other environments.
The core install includes ASE, EMT, and MACE-MP. ChemGraph exposes only the
calculators available in the current environment. Add extras as needed (with
uv tool install, pass them as uv tool install "chemgraph[uma]"):
| Capability | Install | Notes |
|---|---|---|
| TBLite / xTB | pip install "chemgraph[calculators]" |
May need a Fortran toolchain without a wheel |
| UMA / FAIRChem | pip install "chemgraph[uma]" |
Use a separate environment from MACE (e3nn conflict) |
| MACE-Polar | See MACE downloads | Git-only add-on; enables dipole/IR workflows |
| Docking, XANES, RAG | docking, xanes, rag extras |
Docking also needs AutoDock Vina |
| Distributed execution | parsl, globus_compute, ensemble_launcher, academy extras |
See HPC and Academy |
| NWChem, ORCA | Install the executables separately | Must be on PATH or configured through ASE |
See optional extras and calculators for details.
Use a source checkout for development, notebooks, the Streamlit UI, and unreleased changes:
git clone https://github.com/argonne-lcf/ChemGraph.git
cd ChemGraph
uv venv .venv && source .venv/bin/activate
uv pip install -e .Or run the published image, which supports the CLI, Streamlit, MCP, and JupyterLab:
docker run --rm -it -e OPENAI_API_KEY -v "$PWD/cg_logs:/app/cg_logs" \
ghcr.io/argonne-lcf/chemgraph:latest \
chemgraph run -q "What is the SMILES string for aspirin?"See install from source and Docker support.
| Goal | Start here |
|---|---|
| Run queries, interactive sessions, and resumes | CLI guide |
| Pick an agent architecture | Workflows and skills |
| Embed an agent in Python | Python API |
| Use the browser interface | Streamlit interface (source checkout required) |
| Connect chemistry tools to another agent | MCP servers |
| Choose a calculator or add spectroscopy and docking | Calculators and examples |
| Scale to HPC or multi-agent campaigns | HPC and Academy |
| Configure providers, MCP, and backends in TOML | Configuration (never commit API keys) |
| Run in a container or cluster | Docker and Kubernetes |
| Diagnose a failed run | Troubleshooting |
| Workflow | Use it for | Requirements |
|---|---|---|
single_agent |
Molecule lookup, ASE calculations, and reports | Default; start here |
main_agent |
Durable workspace sessions with skills, files, shell, and specialist delegation | Interactive, or headless with --dangerously-skip-approvals |
multi_agent |
Planner/executor decomposition and parallel subtasks | More model calls |
molecular_docking |
Ligand/receptor docking with AutoDock Vina | docking extra and Vina |
rag_agent |
Questions over PDF/text documents plus chemistry tools | rag extra |
single_agent_xanes |
XANES retrieval, simulation, and plotting | xanes extra, MP_API_KEY and/or FDMNES_EXE |
The workflow guide covers
deep_agent, gRASPA, and development workflows.
chemgraph run --interactive --workflow main_agent --workspace .Workspace sessions can run shell commands and modify host files. Tool actions are reviewed by default, and host shell access is not confined to the workspace; see the CLI guide for approvals and session persistence.
ChemGraph.run() is asynchronous:
import asyncio
from chemgraph.agent.llm_agent import ChemGraph
async def main():
agent = ChemGraph(model_name="gpt-4o-mini", return_option="last_message")
result = await agent.run("What is the SMILES string for aspirin?")
print(result.content)
asyncio.run(main())Expose the general chemistry tools to any MCP client over stdio, or over
streamable HTTP at http://localhost:9003/mcp/:
python -m chemgraph.mcp.mcp_tools
python -m chemgraph.mcp.mcp_tools --transport streamable_http --host 127.0.0.1 --port 9003With a uv tool install, prefix these with uv tool run --from chemgraph.
Publications, releases, talks, and media coverage are collected in the news archive.
If ChemGraph supports your research, cite:
Thang D. Pham, Aditya Tanikanti, and Murat Keçeli. “ChemGraph as an agentic framework for computational chemistry workflows.” Communications Chemistry 9, 33 (2026). https://doi.org/10.1038/s42004-025-01776-9
BibTeX for this article and for the HPC orchestration, ChemGraph-XANES, and ChemGraph-IR papers is on the citation page.
Contributions are welcome. See CONTRIBUTING.md for development setup and required checks. For help, see troubleshooting or open an issue.
ChemGraph is distributed under the Apache License 2.0.