scaps-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scaps-mcp run a J-V simulation on my perovskite solar cell and report the efficiency"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
scaps-mcp
MCP server for SCAPS-1D, the one-dimensional solar cell simulator of the University of Gent. It drives your own SCAPS installation headless and gives any MCP client device design, simulation, batches, curve fitting, result analysis and realism checks.
SCAPS is not included. Request it from its authors as described on the SCAPS website and follow their conditions of use, which include citing SCAPS in publications.
Capabilities
Devices: describe any
.def, edit it with every SCAPSsetcommand, load.materialfiles into layers, create devices from scratch (up to 7 layers, 7 defects per layer, 3 defects per interface), and set solver numerics that scripts cannot reach.Simulation: J-V, QE, C-V and C-f with any working point, illumination side, spectrum or generation model, ND filter and cut-off; energy band, generation-recombination and AC profiles.
Batches: grid or paired sweeps over any
setoractionkey, including temperature, intensity and bias.Fitting and optimisation: bounded Nelder-Mead against one or several measured curves (light and dark J-V, QE, C-V), or towards maximum, minimum or target efficiency, Voc, Jsc or FF.
Input files: import shared
.def,.material, absorption, spectrum, generation, filter, grading and measurement files, or write them from data with unit conversion (absorption from alpha or extinction coefficient k).Analysis: Shockley-Queisser limit of the absorber under the spectrum used, QE-integrated Jsc, Mott-Schottky built-in voltage and doping, band offsets at every interface.
Realism checks: results above the detailed-balance limit, missing radiative recombination, ideal interfaces, band spikes and cliffs, compensating defects, implausible densities of states, default absorption models and other common causes of unphysical SCAPS studies.
Jobs: long runs continue in the background with progress, waiting and cancellation.
Validation: every key and value is checked against the command list of the installed SCAPS version before SCAPS starts.
Related MCP server: FD Solutions MCP Server
Requirements
SCAPS-1D 3.3 (tested with 3.3.12)
Python 3.11 or newer
Setup on Windows
Install SCAPS with its installer into a folder you can write to. SCAPS uses its installation folder as its working folder, and its authors advise against Program Files. Copy any SCAPS update files over the installed ones and check that the server finds it:
uvx scaps-mcp doctorSetup on Linux (optional)
SCAPS is a Windows program; on Linux it runs headless under Wine and Xvfb. Install both (Debian and Ubuntu):
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install wine wine32:i386 xvfbCreate a 32-bit prefix and install SCAPS into it, from the folder holding the unpacked SCAPS installer:
export WINEARCH=win32 WINEPREFIX="$HOME/scaps/prefix"
xvfb-run -a bash -c 'wineboot -i && wineserver -w'
xvfb-run -a bash -c 'wine setup.exe /q /AcceptLicenses yes /r:n && wineserver -w'Copy any SCAPS update files over the installed ones and check that the server finds it:
uvx scaps-mcp doctorFinding SCAPS
Without SCAPS_HOME, the server looks for a folder holding scapsXXXX.exe with its def, results and script folders, in folders whose name contains "scaps", one or two levels below:
Windows: the system drive, your user folder, Documents, Desktop, Downloads, Program Files and Program Files (x86).
Linux: your home folder and the
drive_candProgram Filesfolders of Wine prefixes:~/.wine,$WINEPREFIX,$SCAPS_WINEPREFIX, winetricks prefixes and prefixes inside home folders named likescaps.
When several installations are found, the newest SCAPS version is used. scaps_status and doctor show the folder in use and any others. Set SCAPS_HOME to choose one yourself.
Configuration
Variable | Meaning | Default |
| SCAPS folder containing | found automatically |
| executable name | newest |
| seconds per SCAPS run | 300 |
| where run inputs and results are kept | user cache folder |
| Linux only: Wine prefix | the prefix containing the SCAPS folder |
| Linux only: Wine binaries | found on the system |
| Linux only: |
|
Plots need the optional extra: uvx --with matplotlib scaps-mcp, or install scaps-mcp[plot].
Clients
Claude Code:
claude mcp add --transport stdio scaps -- uvx scaps-mcpStraight from the repository instead of PyPI:
claude mcp add --transport stdio scaps -- uvx --from git+https://github.com/asiff00/scaps-mcp scaps-mcpAdd --env SCAPS_HOME=<folder> before scaps when SCAPS is somewhere the server does not search.
Project configuration (.mcp.json), with a long tool timeout for batches and fits:
{
"mcpServers": {
"scaps": {
"command": "uvx",
"args": ["scaps-mcp"],
"timeout": 3600000
}
}
}Other MCP clients start the same command, with SCAPS_HOME in the server environment only when SCAPS is somewhere the server does not search.
Tools
Tool | Purpose |
| Installation, version, run folder, plotting support, running jobs |
| Definitions, materials, spectra, absorption, grading, measurement and other files |
| Search the installed SCAPS command list |
| Layers, defects, interfaces with band offsets, contacts, realism checks |
| Set commands, materials and solver numerics, saved as a new definition |
| New device from a layer, defect, interface and contact description |
| Add a shared SCAPS file and report missing referenced files |
| Write absorption, spectrum, generation, filter, grading or measurement files from data |
| One simulation with metrics, curves, profiles, analysis and checks |
| Grid or paired sweeps over set and action keys |
| Fit measured curves or optimise a figure of merit |
| List, inspect, wait for or cancel runs |
| Paginated tables from any result file |
| PNG plot of result curves and profiles |
| Validated SCAPS script for recorder, math, loops and tandem workflows |
| Detailed-balance limits for given band gaps and spectrum |
Definitions and run files are also available as scaps://definitions/{name} and scaps://runs/{run_id}/{file} resources.
Conventions
Keys and units follow the SCAPS script language: thickness in um, densities in cm^-3, interface densities in cm^-2, mobility in cm^2/Vs, velocity in cm/s, cross sections in cm^2, energies in eV, temperature in K. Layers, defects and interfaces count from 1, and layer 1 touches the left (back) contact. Contacts are addressed as contactleft and contactright.
Scripts cannot add the first bulk defect to a layer; scaps_create_device inserts one and configures it. Grading laws, per-level parameters of multivalent defects and the GUI curve fitter have no script commands; use grading files, scaps_optimize and definitions made in the GUI.
Safety
One SCAPS process runs per installation at a time, guarded by a file lock (fcntl on Linux, msvcrt on Windows) that all processes honour. Stopping the server, including with SIGTERM, stops the SCAPS process it started; a process left behind by a crash is stopped by the next run. File names must be bare names inside SCAPS folders. Scripts may not run system commands or open blocking dialogs. For isolation, remove the Wine drive mapping of the host root from the prefix.
Companion skill
The scaps-1d skill teaches an agent SCAPS workflows and realism rules. It works on its own and uses these tools when they are available.
Development
uv sync
uv run pytest
uv run pytest -m scaps
uv run ruff check src testsCitation
Simulations made with SCAPS should cite M. Burgelman, P. Nollet and S. Degrave, Modelling polycrystalline semiconductor solar cells, Thin Solid Films 361-362 (2000) 527-532, doi:10.1016/S0040-6090(99)00825-1.
License
MIT
Available Tools
16 toolsscaps_batchBatch SCAPS simulationsA
Run one SCAPS session over many parameter values and tabulate the J-V metrics of every point.
Covers thickness, doping, defect, band offset, temperature, intensity and bias studies. Every point's files are kept for scaps_results and scaps_plot.
Inputs: variables (required), definition (required), mode, actions, +7 more. Returns: checks, points, run_id, status, +6 more
scaps_create_deviceCreate a SCAPS deviceADestructiveIdempotent
Build a new device from scratch and save it as a .def file.
A layer may name a .material file ('material': 'CIGSe.material'); its properties apply first and explicit keys override them.
Inputs: name (required), layers (required), options, numerics, +4 more. Returns: notes, device, run_id, definition
scaps_describe_deviceDescribe a SCAPS deviceARead-onlyIdempotent
Read a .def file: layers, bulk defects, interfaces with band offsets, contacts and realism checks.
Fields use script names and units, so any value can be passed back as a parameter (layers[0].NA -> 'layer1.NA'). Graded layers report their base value.
Inputs: definition (required). Returns: units, checks, layers, contacts, +5 more
scaps_edit_deviceEdit a SCAPS deviceBDestructiveIdempotent
Change a device and save it as a .def file: parameters, layers, defects, materials and solver settings.
Inputs: base (required), save_as (required), numerics, materials, +2 more. Returns: notes, device, run_id, definition
scaps_import_fileImport a SCAPS fileADestructiveIdempotent
Add a SCAPS file someone shared (device .def, .material, .abs, spectrum, measurement...) to the installation.
Definitions and materials are parsed to confirm they are valid, and files they reference but that are missing (absorption, grading, filter) are listed.
Inputs: kind (required), name (required), content (required), overwrite. Returns: file, kind, summary, missing_references
scaps_jobsManage SCAPS jobsA
List recent runs, or get, wait for or cancel one. A finished job includes its full result.
Inputs: limit, action, job_id, wait_seconds. Returns: jobs, result
scaps_list_filesList SCAPS filesBRead-onlyIdempotent
List files in a SCAPS data folder: definitions, spectra, absorption, grading, generation and more.
Inputs: kind, limit, offset, contains. Returns: kind, files, total
scaps_optimizeFit or optimise a SCAPS deviceA
Fit device parameters to measured curves, or optimise efficiency, Voc, Jsc or FF, by bounded Nelder-Mead.
Replaces the GUI-only SCAPS curve fitter and supports several measurements at once (light and dark J-V, QE, C-V). Each simplex step is one SCAPS session per measurement condition; long runs continue as a job past wait_seconds, so poll with scaps_jobs.
Inputs: goal (required), variables (required), definition (required), metric, +8 more. Returns: best, checks, run_id, status, +6 more
scaps_plotPlot SCAPS resultsCRead-onlyIdempotent
Render result curves as a PNG image. Requires the optional 'plot' extra.
Inputs: files (required), run_id (required), x, y, +5 more.
scaps_resultsRead SCAPS resultsARead-onlyIdempotent
Return one table of a result file: J-V, QE, C-V, C-f curves or band, generation and AC profiles.
Inputs: run_id (required), file, step, table, +3 more. Returns: file, info, kind, rows, +6 more
scaps_run_scriptRun a SCAPS scriptADestructive
Run a SCAPS script for workflows beyond the other tools: recorder, curve fitting, math, loops, tandem.
The server prepends quit and error-log settings and 'clear all'. Commands are checked against the installed SCAPS; file names must be bare; system commands are rejected. Results saved with 'save results. name' are collected into the run.
Inputs: script (required), timeout_s, wait_seconds, validate_only. Returns: files, run_id, status, seconds, +4 more
scaps_script_referenceSearch SCAPS script commandsARead-onlyIdempotent
Search the command list of the installed SCAPS version.
layer, defect, interface and IFdefect stand for numbered forms (layer2, defect1); contact stands for contactleft or contactright; marks commands without a value.
Inputs: query (required), limit. Returns: query, total, source, commands
scaps_simulateRun a SCAPS simulationA
Simulate a device: J-V metrics, QE, C-V, C-f and spatial profiles, with analysis and realism checks.
Analysis gives the absorber's Shockley-Queisser limit, QE-integrated Jsc and a Mott-Schottky fit of C-V. Overrides apply to this run only; files stay available through scaps_results and scaps_plot.
Inputs: definition (required), actions, profiles, spectrum, +8 more. Returns: files, checks, curves, run_id, +9 more
scaps_sq_limitShockley-Queisser limitBRead-onlyIdempotent
Detailed-balance Jsc, Voc, FF and efficiency limits for given band gaps under a SCAPS spectrum.
Inputs: band_gaps_ev (required), spectrum, temperature_k. Returns: limits, spectrum
scaps_statusSCAPS installation statusARead-onlyIdempotent
Report the SCAPS installation in use and how it was found, other installations, run folder and jobs.
Inputs: no named parameters. Returns: busy, plotting, runs_dir, timeout_s, +8 more
scaps_write_dataWrite a SCAPS input fileBDestructiveIdempotent
Write numeric data as a SCAPS input file with the right format and units.
Use it for measured absorption (alpha or extinction coefficient k), custom spectra, external optical generation profiles, contact filters, grading profiles and measurement files for comparison.
Inputs: x (required), y (required), kind (required), name (required), +15 more. Returns: file, kind, folder, points
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target clearly distinct actions (create/edit/describe device, write data, import file, plot, sq_limit). The main overlap is among the simulation family — scaps_simulate, scaps_batch, scaps_optimize, scaps_run_script — but their descriptions draw usable boundaries (single run, parameter sweep, fitting, escape hatch). Minor potential confusion between scaps_results and scaps_plot, and between scaps_create_device and scaps_edit_device, is resolved by the descriptions.
All tools share the scaps_ prefix and mostly follow verb_noun (write_data, list_files, create_device, edit_device, describe_device, run_script, import_file). A few deviate to bare verbs or nouns (scaps_simulate, scaps_status, scaps_jobs, scaps_results, scaps_batch), but the pattern remains predictable and readable.
16 tools is at the upper end of the comfortable range, but the domain (device construction, simulation, batch/optimization, results, jobs, file management, scripting) genuinely warrants this surface. Each tool maps to a real workflow step rather than padding.
Coverage is strong: create/edit/describe devices, simulate, batch, optimize, retrieve/plot results, manage jobs, import files, query script reference, and a low-level script escape hatch. Gaps are minor — no explicit delete/cleanup of run artifacts and no dedicated material-authoring tool, though scaps_write_data and scaps_edit_device partially cover these.
Maintenance
Related MCP Connectors
Build, run and analyse block-diagram simulations: PID, Bode, FFT, optimisation and code export.
Simulate electric UAV powertrains and search a public motor, propeller and battery database.
NREL MCP — wraps the US National Renewable Energy Laboratory developer API
Optical design, simulation and analysis with GPU-powered ray tracing. Import from Zemax and CAD.
Related MCP Servers
- AlicenseAqualityDmaintenanceA thin MCP server that wraps spicelib for circuit simulation. Exposes tools for running AC, transient, DC op, and parameter sweep analyses, enabling behavioral model fitting through iterative simulation and measurement comparison.412 PyPI8GPL 3.0
- AlicenseBqualityCmaintenanceEnables 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.20Apache 2.0
- AlicenseBqualityBmaintenanceEnables building wire-connected native schematics, visually checking them, editing values, and running native frequency/transient analyses plus symbolic formulas and plots, with results saved as CSV/PNG and openable in the separately installed application.29MIT
- AlicenseAqualityBmaintenanceEnables building, saving, inspecting, and previewing supported circuits, plus running headless harmonic-balance simulations and comparing parameter variants without using the desktop UI.21MIT