Skip to main content
Glama

Vishwakarma MCP

Run Quantum ESPRESSO from Claude Desktop. Vishwakarma is a local MCP server that lets an AI assistant set up, run and read density-functional-theory calculations on your own machine, plot the results, and pass band-structure data into a device simulation.

Everything runs locally. No calculation data leaves your computer.

What it can do

Tool

What it does

vishwakarma_health

Reports which Quantum ESPRESSO programs were found and where jobs are stored

vishwakarma_generate_input

Writes a Quantum ESPRESSO input file for review, without running it

vishwakarma_run_scf

Self-consistent total-energy calculation (pw.x)

vishwakarma_run_relax

Ionic or variable-cell relaxation, then a final SCF

vishwakarma_run_bands

Band structure along a k-path

vishwakarma_run_dos

Density of states

vishwakarma_run_phonon

Phonons (ph.x)

vishwakarma_run_neb

Nudged elastic band

vishwakarma_run_hp

Hubbard U from linear response (hp.x)

vishwakarma_parse_output

Reads energies, forces, convergence from a job's output

vishwakarma_list_pseudopotentials

Lists the pseudopotential files available

vishwakarma_get_job_status, vishwakarma_list_jobs

Job bookkeeping

vishwakarma_plot

DOS, 2D band structure, 3D band surfaces, charge-density isosurfaces

vishwakarma_device_material

Turns DFT bands into device-simulation material parameters

vishwakarma_device_simulate

Drift-diffusion simulation of a diode or MOSFET (DEVSIM)

Related MCP server: ABACUS MCP Server

Install (Linux)

git clone <this repository>
cd vishwakarma-mcp
./install.sh --add-to-claude

Then restart Claude Desktop.

The installer creates one folder, ~/.local/share/vishwakarma, containing a private environment with Quantum ESPRESSO 7.5, MPI, Python and this package. It needs no root access and changes nothing system-wide. At the end it runs a silicon calculation and compares the energy with a recorded reference, so you know the installation computes correctly before you use it.

Without --add-to-claude the installer prints the block to paste into ~/.config/Claude/claude_desktop_config.json yourself:

{
  "mcpServers": {
    "vishwakarma": {
      "command": "/home/YOU/.local/share/vishwakarma/env/bin/vishwakarma-mcp",
      "env": { "VISHWAKARMA_HOME": "/home/YOU/.local/share/vishwakarma" }
    }
  }
}

Other options: --prefix DIR, --no-device, --no-self-test.

If you already have Quantum ESPRESSO

pip install ".[device]"
QE_BIN_DIR=/path/to/qe/bin vishwakarma-mcp doctor --self-test

Pseudopotentials

Pseudopotential files are not shipped with this repository. The installer downloads the one silicon file the self-test needs. Fetch others by file name:

vishwakarma-mcp fetch-pseudo Zn.pbe-dnl-rrkjus_psl.1.0.0.UPF Se.pbe-dn-rrkjus_psl.1.0.0.UPF

Files come from the Quantum ESPRESSO pseudopotential archive and are stored in ~/.local/share/vishwakarma/pseudo. You can also copy your own UPF files into that folder, or point QE_PSEUDO_DIR at a folder you already have.

Checking an installation

vishwakarma-mcp doctor              # binaries, Python modules, folders
vishwakarma-mcp doctor --self-test  # also runs silicon at 1 and 2 MPI processes
vishwakarma-mcp doctor --json       # machine-readable report

Settings

All optional. With none set, the server uses the folder it was installed into.

Variable

Meaning

Default

VISHWAKARMA_HOME

Where jobs and pseudopotentials live

~/.local/share/vishwakarma

QE_BIN_DIR

Folder containing pw.x and the other programs

next to the Python that runs the server, else PATH

VISHWAKARMA_WORKDIR

Job folder

$VISHWAKARMA_HOME/jobs

QE_PSEUDO_DIR

Pseudopotential folder

$VISHWAKARMA_HOME/pseudo

VISHWAKARMA_CPUS

CPUs the jobs may use, e.g. 0-2,6-8

half of the physical cores

MP_API_KEY

Materials Project key, for fetching structures

unset (feature off)

VISHWAKARMA_CUSTODY_URL, VISHWAKARMA_CUSTODY_KEY

Optional server that records each result

unset (off)

Known limits

  • Linux only. Windows and macOS are not supported yet.

  • A tool call waits up to 45 s for its calculation (wait_seconds changes that). A longer run returns a run_id and carries on in the background; vishwakarma_get_job_status with that run_id returns the full result when it is done. If the server restarts mid-run, jobs already launched finish, but later steps of that workflow are not started. There is no cancel tool yet.

  • Validated against reference values for silicon only (see validation/device/SI_VALIDATION.md). Other materials run, but their results have not been benchmarked here.

  • Plotting reads the save folder a job points to. If a later job reuses the same folder, plotting the earlier job reads the newer data.

  • The charge-density plot has not been compared with an external reference.

Development

pip install -e ".[device,test]"
VK_SKIP_SLOW=1 python -m pytest tests -q

Origin and licence

Vishwakarma began as one agent of the BRAHM research system and was split out so it can be used on its own.

Licensed under the GNU General Public License, version 3 or later (see LICENSE). It runs Quantum ESPRESSO (GPL) as external programs and can use BoltzTraP2 (GPL) and DEVSIM (Apache-2.0).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI-driven first-principles calculations for quantum chemistry and materials science using ABACUS, with tools for SCF, structure optimization, molecular dynamics, band structure, and intelligent parameter suggestions.
      9
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables first-principles calculations (SCF, structure optimization, molecular dynamics, etc.) for quantum chemistry and materials science using ABACUS, with intelligent parameter suggestions and result analysis through natural language.
      GPL 3.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables LLM agents to run verified DFT materials workflows (structure fetch, relaxation, band/DOS) with automated convergence gates and physics validation, ensuring every result is machine-verified with a complete evidence trail.
      5
      3
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to drive local photonic simulation software through its Python API, supporting modeling and layout, property setup, simulation runs, parameter sweeps, job management, and result analysis.
      20
      Apache 2.0