Dft Autopilot Mcp

DFT AutoPilot

English | [简体中文](README.zh-CN.md)

> Run first-principles DFT calculations (Quantum ESPRESSO · VASP · Gaussian) from a chat client — on your own HPC. An MCP server + a Claude skill that turns "compute the DOS of NiO with Hubbard U" into a full model → compute → analyze → report workflow.

[](https://www.npmjs.com/package/dft-autopilot-mcp) [](https://www.npmjs.com/package/dft-autopilot-mcp) [](LICENSE) [](https://modelcontextprotocol.io)

DFT AutoPilot is BYO‑HPC (Bring Your Own HPC): it provides the orchestration — input generation, job submission, result extraction, literature/materials lookup, plotting and reporting — and runs everything on a compute backend you configure: a national SuperComputing network (SCNet), any Slurm cluster over SSH, or your local machine. It ships with no compute account of its own.

---

⚠️ Disclaimer & responsibility (read this)

DFT AutoPilot only orchestrates calculations using credentials and compute allocations that you supply. By using it you understand and agree that:

• You run jobs on your own account / HPC allocation, at your own cost and risk. You are solely responsible for all compute charges, resource usage, job behavior, and data produced.
• You are responsible for complying with the Terms of Service of your compute provider (e.g. your supercomputing center, SCNet, or institutional cluster), and with the licenses of the DFT engines you use (Quantum ESPRESSO is GPL; VASP and Gaussian are proprietary and require your own valid license).
• This software is provided "AS IS", without warranty of any kind, under the Apache‑2.0 License. The authors are not liable for compute costs, wasted allocation, data loss, failed or incorrect calculations, or any damages arising from its use (see LICENSE sections 7–8).
• The maintainers run no hosted service and have access to none of your accounts or data. This project is not affiliated with or endorsed by SCNet, the Quantum ESPRESSO project, VASP, or Gaussian.

Scientific results must be validated by a qualified researcher. An automated agent can make physics mistakes — always review the plan and the numbers.

---

Features

• 3 engines: Quantum ESPRESSO, VASP, Gaussian 16 — input generation, submission, and result parsing for each.
• BYO‑HPC backends: local · slurm (any Slurm cluster over SSH) · scnet (national SuperComputing network, with your own account).
• 19 MCP tools covering the whole pipeline (see below).
• dft-compute skill: an autonomous "computational chemist" workflow with a mandatory plan‑before‑compute review and per‑parameter _reasons auditing.
• Knowledge built in: SSSP cutoff recommendations, DFT+U guidance, QE/VASP parameter references, troubleshooting notes.

Tools

| Group | Tools | |------|------| | QE | create_qe_input, extract_dft_results, lookup_pseudopotential, lookup_hubbard_u, import_structure | | VASP | create_vasp_input, extract_vasp_results | | Gaussian | create_gaussian_input, extract_gaussian_results | | Jobs (backend‑agnostic) | submit_compute_job, check_job_status, download_job_results, preview_remote_file, cancel_job | | Helpers | run_pymatgen, plot_chart, write_report, search_literature, search_materials |

---

Prerequisites

• Node.js ≥ 18 (the MCP server is Node/TypeScript).
• For run_pymatgen, import_structure, and structure handling: Python 3 with pymatgen and ase installed and on PATH.
• The DFT engines themselves on your chosen backend (QE / VASP / Gaussian — obtained and licensed by you).
• For slurm: passwordless SSH to your cluster's login node. For scnet: your own SCNet account (AccessKey/SecretKey).

> The MCP install does not install Python, the engines, or pseudopotentials — those are yours to provide.

---

Install

A. Claude Code plugin (recommended — skill + server in one)

/plugin marketplace add The66user/dft-autopilot-mcp
/plugin install dft-autopilot@dft-autopilot-marketplace

You'll be prompted for configuration (compute backend, API keys) at install time; secrets are stored in your OS keychain.

B. Any MCP client via npm (e.g. Claude Code CLI)

claude mcp add --env COMPUTE_PROVIDER=local --env MP_API_KEY=YOUR_KEY \
  dft-autopilot -- npx -y dft-autopilot-mcp

C. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "dft-autopilot": {
      "command": "npx",
      "args": ["-y", "dft-autopilot-mcp"],
      "env": {
        "COMPUTE_PROVIDER": "local",
        "MP_API_KEY": "YOUR_MATERIALS_PROJECT_KEY"
      }
    }
  }
}

A one‑click .mcpb bundle is also attached to GitHub Releases (Claude Desktop → Settings → Extensions). Note: the .mcpb bundles the Node server only — Python/pymatgen and the DFT engines must already be on your machine.

---

Configure the compute backend

Set COMPUTE_PROVIDER and the matching variables (full list in [server/.env.example](server/.env.example)).

local

Runs on this machine. Requires the engines installed locally.

COMPUTE_PROVIDER=local

slurm — any Slurm cluster over SSH

COMPUTE_PROVIDER=slurm
SLURM_HOST=you@login.cluster.edu        # or a ~/.ssh/config alias; passwordless SSH required
SLURM_REMOTE_BASE_DIR=/scratch/you/dft-autopilot
SLURM_PARTITION=cpu
SLURM_MODULES=module load quantum-espresso/7.4
SLURM_PSEUDO_DIR=/scratch/you/pseudo    # optional: rewrites QE pseudo_dir

scnet — national SuperComputing network (your own account)

COMPUTE_PROVIDER=scnet
SCNET_USER=...
SCNET_ACCESS_KEY=...
SCNET_SECRET_KEY=...
SCNET_CLUSTER_ID=...
SCNET_HPC_URL=...
SCNET_EFILE_URL=...
# ...see .env.example for the full set

> No credentials are bundled. Whatever backend you pick runs under your account.

---

Connecting your DFT engines

DFT AutoPilot calls engines you have already installed — it never bundles or installs them. This section is only about how the orchestrator finds and runs them on each backend. (Compiling QE, or installing a licensed VASP/Gaussian build, is out of scope — see each engine's own docs.)

local

Jobs run through bash -lc (your login shell), so the executables (pw.x, vasp_std, g16, …) just need to be on PATH in a login shell. Easiest is to activate the environment in your ~/.bashrc:

# ~/.bashrc
conda activate qe          # or: module load quantum-espresso/7.4

• QE pseudopotentials: the pseudo_dir in the generated .in should point at your local UPF folder (QE_PSEUDO_DIR, or set it when generating input).
• VASP: make sure POTCAR is present in the job directory.

slurm

Engines are loaded inside the generated sbatch script from SLURM_MODULES (and optionally SLURM_QE_BIN_DIR, prepended to PATH):

SLURM_MODULES=module load quantum-espresso/7.4; module load vasp/6.4
SLURM_QE_BIN_DIR=/opt/qe/bin            # optional, if the binaries aren't in a module

• QE pseudopotentials: set SLURM_PSEUDO_DIR — the pseudo_dir in your .in is rewritten to this path automatically at submit time.
• VASP: place POTCAR in the job dir (it's uploaded with the inputs); the Slurm backend does not assemble POTCAR from a library.

scnet

Each engine loads from an env script you point it at; for VASP, POTCAR is auto-assembled from a library by element:

SCNET_QE_ENV_SCRIPT=/path/to/qe-env.sh        SCNET_QE_PATH=/path/to/pw.x
SCNET_PSEUDO_DIR=/path/to/pseudo
SCNET_VASP_ENV_SCRIPT=/path/to/vasp-env.sh    SCNET_POTCAR_DIR=/path/to/potcar-library
SCNET_GAUSSIAN_ENV_SCRIPT=/path/to/g16-env.sh

> Full variable list with comments: [server/.env.example](server/.env.example).

---

Usage

Talk to your client in plain language — the dft-compute skill drives the whole pipeline. By default it researches parameters, shows you a plan, and waits for your approval, then generates inputs, submits to your backend, monitors, downloads, parses results, and writes a report. Every parameter it picks comes with a cited reason.

A typical session

> You: Relax bulk Si with Quantum ESPRESSO, then compute its band structure, on my Slurm cluster. > > Agent: (looks up SSSP cutoffs, scans literature) Here's the plan: > 1. vc-relax — ecutwfc 50 / ecutrho 400 Ry (SSSP efficiency), 8×8×8 k-grid > 2. scf on the relaxed structure > 3. bands along Γ–X–W–K–Γ–L > 16 cores, ≈20 min. Approve? > > You: go > > Agent: (generates inputs → submits → monitors → downloads → parses) Done. Indirect gap ≈0.6 eV (Γ→X), relaxed a = 5.47 Å. Report at Si_bulk/report.md, band plot under Si_bulk/04_bands/.

More things you can ask

• "Optimize a water molecule with Gaussian at B3LYP/6-311+G(d,p), then a frequency check."
• "Compute the DOS of NiO with Hubbard U — look up the U value first."
• "Find the Li-diffusion NEB barrier between these two structures with VASP."

> Want to skip the review and run immediately? Just say so (e.g. "skip the plan, go ahead").

---

License

Apache‑2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Third‑party data/engine attributions (SSSP, QE/VASP/Gaussian) are in NOTICE.

Personal and academic use is free. If you'd like commercial support, a managed/end‑to‑end DFT service, or to collaborate, see the contact in the repository profile.

Contributing & security

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). Installing any plugin runs code that talks to your HPC with your credentials — review the source and only configure backends you trust.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: The66user
• Source: The66user/dft-autopilot-mcp
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/dft-autopilot-mcp

Install and usage instructions live in the source repository linked above.