README.md

metadata

title: Quantum ESPRESSO MCP Server
emoji: ⚛️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.8.0
app_file: app.py
pinned: false
license: mit
tags:
  - mcp
  - quantum-espresso
  - dft
  - materials-science
  - building-mcp-track-enterprise
  - building-mcp-track-consumer

⚛️ Quantum ESPRESSO MCP Server

Run DFT calculations with natural language! An MCP server that enables LLMs to perform first-principles quantum mechanical simulations.

🎯 What This Does

This MCP server allows AI agents (Claude, GPT, etc.) to:

• Calculate total energies of materials (Si, Fe, Cu, GaAs...)
• Compute band structures and find band gaps
• Run density of states calculations
• Optimize crystal structures (relax atoms and cells)
• Handle magnetic materials automatically (Fe, Co, Ni...)

Just say: "Calculate the band structure of silicon" - and the AI does the rest!

🎥 Demo Video

📹 Watch Demo on YouTube

📱 Social Media

🐦 X/Twitter Post

🔧 12 MCP Tools Available

Tool	Description
qe_run_scf	Self-consistent field calculation (total energy)
qe_run_relax	Optimize atomic positions
qe_run_vc_relax	Variable-cell relaxation
qe_workflow_bandstructure	Complete band structure workflow
qe_workflow_dos	Density of states calculation
qe_workflow_relax_and_scf	Relax then accurate SCF
qe_load_structure	Load/inspect structures
qe_get_kpath	Get k-path for band structure
qe_suggest_kpoints	Auto-suggest k-point grid
qe_list_pseudopotentials	List 69 available elements
qe_validate_structure	Check structure for issues
qe_status	Server status

✨ Key Features

🧠 Smart Auto-Detection

• Only structure is required - everything else is auto-detected!
• K-points automatically chosen based on cell size
• Cutoffs from SG15 pseudopotentials
• Spin polarization auto-enabled for Fe, Co, Ni, Mn, Cr, V

📚 69 Elements Supported

Full periodic table coverage with SG15 ONCV pseudopotentials:

Ag, Al, Ar, As, Au, B, Ba, Be, Bi, Br, C, Ca, Cd, Cl, Co, Cr, Cs, Cu, F, Fe, Ga, Ge, H, He, Hf, Hg, I, In, Ir, K, Kr, La, Li, Mg, Mn, Mo, N, Na, Nb, Ne, Ni, O, Os, P, Pb, Pd, Pt, Rb, Re, Rh, Ru, S, Sb, Sc, Se, Si, Sn, Sr, Ta, Tc, Te, Ti, Tl, V, W, Xe, Y, Zn, Zr

🎯 8 Prompts for Guided Workflows

• band_structure - Band structure calculation guide
• dos_calculation - DOS workflow
• geometry_optimization - Structure relaxation
• convergence_test - Parameter testing
• surface_calculation - Surface energy
• magnetic_calculation - Magnetic properties
• troubleshoot - Diagnose problems
• compare_structures - Compare materials

🚀 Quick Start

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "quantum-espresso": {
      "command": "uv",
      "args": ["--directory", "/path/to/QE_MCP", "run", "qe-mcp"]
    }
  }
}

Then ask Claude:

• "Calculate the total energy of silicon"
• "What's the band gap of GaAs?"
• "Run a spin-polarized calculation for iron"

📊 Example Results

Silicon SCF

Total Energy: -214.49 eV
Fermi Energy: 6.30 eV
Converged: 4 iterations

Iron (Magnetic)

Total Energy: -3220.53 eV
Magnetization: 7.63 μB
Spin-polarized: Auto-enabled

GaAs Band Structure

Band Gap: 0.56 eV (indirect)
VBM → CBM: Γ → X

🏗️ Architecture

User (natural language)
    ↓
LLM (Claude/GPT)
    ↓
MCP Protocol
    ↓
QE-MCP Server (Python)
    ↓
Docker Container (Quantum ESPRESSO v6.7)
    ↓
DFT Calculation Results
    ↓
Structured Output (JSON)

🛠️ Tech Stack

• Quantum ESPRESSO v6.7MaX - DFT engine
• MCP SDK (mcp>=1.0.0) - Model Context Protocol
• ASE 3.26 - Atomic Simulation Environment
• Docker - Containerized QE
• SG15 ONCV - Pseudopotentials (69 elements)

👤 Team

• Joseph Frimpong - @frimpsjoe

📜 License

MIT License

---

Built for MCP's 1st Birthday Hackathon 🎂