Vishwakarma MCP
README.md
# 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) |
## Install (Linux)
```bash
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:
```json
{
"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
```bash
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:
```bash
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
```bash
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
```bash
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).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues