Skip to main content
Glama

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 SCAPS set command, load .material files 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 set or action key, 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 doctor

Setup 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 xvfb

Create 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 doctor

Finding 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_c and Program Files folders of Wine prefixes: ~/.wine, $WINEPREFIX, $SCAPS_WINEPREFIX, winetricks prefixes and prefixes inside home folders named like scaps.

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_HOME

SCAPS folder containing scapsXXXX.exe

found automatically

SCAPS_EXE

executable name

newest scaps*.exe

SCAPS_TIMEOUT

seconds per SCAPS run

300

SCAPS_RUNS_DIR

where run inputs and results are kept

user cache folder

SCAPS_WINEPREFIX

Linux only: Wine prefix

the prefix containing the SCAPS folder

SCAPS_WINE, SCAPS_WINESERVER

Linux only: Wine binaries

found on the system

SCAPS_XVFB

Linux only: 0 to use the current display instead of Xvfb

1

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-mcp

Straight from the repository instead of PyPI:

claude mcp add --transport stdio scaps -- uvx --from git+https://github.com/asiff00/scaps-mcp scaps-mcp

Add --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

scaps_status

Installation, version, run folder, plotting support, running jobs

scaps_list_files

Definitions, materials, spectra, absorption, grading, measurement and other files

scaps_script_reference

Search the installed SCAPS command list

scaps_describe_device

Layers, defects, interfaces with band offsets, contacts, realism checks

scaps_edit_device

Set commands, materials and solver numerics, saved as a new definition

scaps_create_device

New device from a layer, defect, interface and contact description

scaps_import_file

Add a shared SCAPS file and report missing referenced files

scaps_write_data

Write absorption, spectrum, generation, filter, grading or measurement files from data

scaps_simulate

One simulation with metrics, curves, profiles, analysis and checks

scaps_batch

Grid or paired sweeps over set and action keys

scaps_optimize

Fit measured curves or optimise a figure of merit

scaps_jobs

List, inspect, wait for or cancel runs

scaps_results

Paginated tables from any result file

scaps_plot

PNG plot of result curves and profiles

scaps_run_script

Validated SCAPS script for recorder, math, loops and tandem workflows

scaps_sq_limit

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 tests

Citation

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 tools
scaps_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 deviceA
DestructiveIdempotent

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 deviceA
Read-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 deviceB
DestructiveIdempotent

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 fileA
DestructiveIdempotent

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 filesB
Read-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 resultsC
Read-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 resultsA
Read-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 scriptA
Destructive

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 commandsA
Read-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 limitB
Read-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 statusA
Read-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 fileB
DestructiveIdempotent

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

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      4
      12 PyPI
      8
      GPL 3.0
    • 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
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      29
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables building, saving, inspecting, and previewing supported circuits, plus running headless harmonic-balance simulations and comparing parameter variants without using the desktop UI.
      21
      MIT