PVsyst MCP Server
English | Español
Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
English | Español
MCP server that automates PVsyst 8.1.7 through its data files and the documented PVsystCLI commands
A Model Context Protocol (MCP) server that automates
PVsyst 8.1.7 from an AI agent — batch simulations, project and variant creation,
component and weather handling, and result extraction — by reading and writing only
PVsyst's data files and running the documented PVsystCLI commands as a black box.
It is the missing API for PVsyst: there is no public scripting interface an agent can call, so this server gives agents one through the artifacts PVsyst already reads and writes.
Unofficial. Not affiliated with, endorsed by or sponsored by PVsyst SA. "PVsyst" is a trademark of its respective owner and is used here only to describe interoperability. This project contains no PVsyst code and redistributes no PVsyst software: you need your own licensed installation. See responsible use.
Hard rules this project follows
- No PVsyst source code, no decompilation.
PVsyst.exeis never opened in Ghidra/IDA;PVsystCLI.exeis only ever run black-box.- No simulation engine is implemented here. When a simulation is needed the MCP shells out to the documented
PVsystCLI run-simulationcommand.- The MCP prepares, duplicates and inspects projects; PVsyst does the physics.
Contents
PVsyst is the reference tool for photovoltaic system design and bankable yield
simulation, and it ships no public API: automation means either writing batch files
for PVsystCLI by hand, or clicking the desktop UI. That gap is exactly what an agent
cannot cross on its own, so this server closes it:
Key=Value "PVObject"
records; the server edits fields, inserts and removes objects without touching a byte
it was not asked to change.Each tool takes a discriminator (accion or que); omitted values use the default shown.
All 15 tools are available by default. The MCP's own calculations are the only opt-in surface.
Every figure comes from PVsyst. By default the MCP only returns what PVsyst computes
(PVsystCLI, the variant it simulates and its PDF report). The MCP's own calculations that
duplicate a PVsyst function sit behind PVSYST_MCP_APROXIMACIONES=1: without it, the actions
that only exist as MCP calculations are absent from tools/list and, if called, answer with the
PVsyst route that replaces them; with it, their result carries origen: "aproximacion_mcp".
Those actions are simular preestimar/barrido, sitio geometria_solar,
resultados medido_vs_simulado and the automatic sizing of disenar_sistema. Actions that keep
PVsyst as their default route stay visible: componente crear_desde_ficha, sitio horizonte_pvgis, resultados p50_p90 and proyecto dimensionar from kwp use PVsyst's windows
and only run the MCP calculation when called with via: "aproximacion" and the flag is on.
Resources (resources/list / resources/read): pvsyst://recetas (task → tool playbook), pvsyst://cobertura (coverage map), pvsyst://formato (file formats), pvsyst://cli (CLI reference), pvsyst://gui (GUI function catalogue and window map). Unknown URIs return JSON-RPC -32602 Recurso desconocido.
* The action has an MCP-calculation branch. Its default is PVsyst; via: "aproximacion" (and, for the actions that only exist as an approximation, the action itself) requires PVSYST_MCP_APROXIMACIONES=1. Without the flag those gate-only actions are hidden from tools/list.
All tools read/write only files under the workspace; nothing is sent anywhere, except the PVGIS requests of meteo_pvgis and, with approximations enabled, horizonte_pvgis and the optional PVGIS fetch of p50_p90 (PVGIS MRcalc, printhorizon and tmy verified live). Meteonorm data is not used: even the horizon block that proyecto anadir copies from a demo is emptied first — see responsible use.
Path scope. Every caller-supplied path (read, list, edit, import/export, capture output, CSV/report destinations, history restore) is confined to the workspace: .. and paths outside it are rejected. Pass permitir_fuera_del_workspace: true to opt out explicitly. History restore always validates the whole manifest first and never writes outside the workspace. Edits refuse files whose PVObject structure is unbalanced, and selectors with malformed segments or indices (pvSubArray[abc]) are errors instead of falling back to [0].
Snapshots of edited files live under UserData/mcp_history/<id>/ (with manifest.json); simulation cache and trial-budget ledger live under UserData/mcp_cache/.
Tool execution is fast (a few milliseconds); the perceived slowness is per-turn model latency plus the size of tool output. Two mitigations are built in:
elapsed_ms — every tool response carries the server-side duration, so
latency can be measured instead of guessed.detalle on every tool: resumen (default) trims arrays to 10 items and long
strings; normal and completo return more. Use completo only when needed.siguiente on successful results suggests the next call in the flow.vista on every answer, success or failure, is the same block for every tool and action:
estado (ok, parcial, error), resumen (one sentence), campos ({clave, valor, unidad, origen, editable};
origen is pvsyst, mcp or aproximacion_mcp), avisos, siguiente ([{tool, argumentos, motivo}], each
executable as written) and recortado ({clave, mostrados, total, pedir_resto}). A failure adds error
(codigo, motivo, causa_probable, que_hacer, claves_validas for input errors). Existing keys do not change.
vista is the answer's block; gui_observar que:vista is the form view by keys — a GUI answer can carry both.Other levers: batch independent calls in one turn, avoid long esperar_segundos
waits (poll instead), and capture screenshots only when needed.
Because the primitives act on the whole data + CLI + GUI surface, the MCP
covers every PVsyst state, computation and dialog — projects, variants, all
component types, site/weather, shadings, models, batch runs, parameter overrides,
licensing, logs, and the mouse-driven GUI tools (3D editor, informative plots,
wizards), which are driven through UI Automation and Win32 (gui_observar /
gui_actuar). Full map: docs/cobertura.md and
the page-by-page inventory in docs/pvsyst_features.md;
the pvsyst://cobertura resource returns the machine-readable version.
sitio {accion:"crear", origen:"coordenadas", latitud, longitud, nombre} → .SIT (reuses an existing site when coordinates match).proyecto {accion:"crear", plantilla, nombre_nuevo, modulo, inversor, n_mod_serie, n_strings}.proyecto {accion:"dimensionar", proyecto, n_mod_serie, n_strings} → writes NModSerie/NStringCh/PNomSizing.editar {accion:"campos", proyecto, ediciones:[…]} → tilt/azimuth, losses, etc.simular {proyecto, site:"…SIT", synthetic_weather:true} (trial-licence runs ask for confirmation when they use two or more executions). Check avisos_pvsyst: that is where PVsyst warns, e.g., about a Vmpp outside the inverter window.resultados {que:"perdidas"}, then que:"mensual", que:"carbono", que:"entregable".PVsyst 8.1.7 installed (default C:\Program Files\PVsyst8.1.7\).
Windows — the GUI bridge uses the Win32 API.
A PVsystCLI licence for unlimited headless simulation. Without
C:\ProgramData\PVsystCLI\PVsystCLI.lic the CLI runs in TRIAL mode (limited days and
executions; entorno accion:licencia shows the counters and the server keeps a ledger,
asks for confirmation before multi-execution runs and caches repeated simulations). To
activate, run yourself "C:\Program Files\PVsyst8.1.7\PVsystCLI.exe" lic-activate -k:<YOUR_KEY>
(entorno accion:licencia_activar prints the command; the server never executes it).
Everything else (files, sites, sizing, GUI) works without a licence.
Rust (any recent stable).
A linker: MSVC (link.exe from VS Build Tools) — or, as used on the
machine this was built on, MinGW-w64 + the GNU toolchain:
winget install BrechtSanders.WinLibs.POSIX.UCRT # gcc/ld for the GNU target
rustup toolchain install stable-x86_64-pc-windows-gnu
rustup override set stable-x86_64-pc-windows-gnu # per-project (this dir)
# make sure <WinLibs>\mingw64\bin is on PATH so cargo finds gcc.exe
cargo build --release
# → target\release\pvsyst-mcp.exe
Run the tests:
cargo test
Download the .mcpb file from the
latest release and
open it (or drag it onto Settings → Extensions). Claude Desktop asks for the PVsyst
workspace, PVsystCLI.exe and PVsyst.exe; leave the paths empty to let
the server auto-detect them. The bundle is built from mcpb/manifest.json.
The bundle does not update itself: install the new .mcpb from each release.
{
"mcpServers": {
"pvsyst": { "command": "npx", "args": ["-y", "pvsyst-mcp"] }
}
}
The npm launcher keeps the server current on its own. Every start runs the newest
binary it has (the packaged one or one downloaded earlier to
%LOCALAPPDATA%\pvsyst-mcp) and, once the server is running, checks npm in a
detached background process. A newer release is downloaded for the next start; the
current session never switches binaries mid-way. Its log is
%LOCALAPPDATA%\pvsyst-mcp\actualizacion.log. Set PVSYST_MCP_AUTO_ACTUALIZAR=0 to
turn it off. Only npm/npx installs update this way; the zip and the .mcpb do not.
Important — the space-in-path gotcha. Command Code does not quote the executable path when it spawns a stdio MCP server, so a
commandcontaining a space (e.g....\PVSYST MCP\...) fails to start silently — the server is listed but never connects, and its tools never appear. Install the binary to a space-free location.
# 1. build release and copy it to C:\pvsyst-mcp\pvsyst-mcp.exe
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
# 2. register it (binary is cmd / cmdc / command-code; use "cmdc" on Windows)
cmdc mcp add --scope user --env PVSYST_WORKSPACE=C:\Users\Lenovo\PVsyst8.1_Data pvsyst -- "C:\pvsyst-mcp\pvsyst-mcp.exe"
cmdc mcp list
mcp.example.json shows a ready-to-copy configuration for that space-free binary. .mcp.json is ignored, so copy the example and adjust the paths:
{
"mcpServers": {
"pvsyst": {
"transport": "stdio",
"enabled": true,
"command": "C:\\pvsyst-mcp\\pvsyst-mcp.exe",
"env": { "PVSYST_WORKSPACE": "C:\\Users\\Lenovo\\PVsyst8.1_Data" }
}
}
}
The tools then appear as mcp__pvsyst__listar_proyectos, etc. Re-run
scripts\install.ps1 after every rebuild.
Any client that speaks MCP over stdio can drive it (Claude Desktop, Cursor, VS Code,
and anything else that reads the usual mcpServers map). Point the client at the
space-free binary and give it the workspace folder:
{
"mcpServers": {
"pvsyst": {
"command": "C:\\pvsyst-mcp\\pvsyst-mcp.exe",
"env": { "PVSYST_WORKSPACE": "C:\\Users\\Lenovo\\PVsyst8.1_Data" }
}
}
}
Keep it local: the server is designed for the workstation that holds your PVsyst licence, not for a shared endpoint — see responsible use.
Client-compatibility notes. The server echoes back the protocolVersion the
client requests when it supports it (2024-11-05, 2025-03-26, 2025-06-18;
Command Code asks for 2025-03-26) and otherwise answers with its latest supported
version, as the MCP spec requires. It exposes five resources (pvsyst://recetas,
pvsyst://cobertura, pvsyst://formato, pvsyst://cli, pvsyst://gui) and seven prompts built
from those recipes. With 2025-06-18, tool results also carry structuredContent;
long simulations report progress and accept notifications/cancelled. Tool
arguments are type-checked against each tool's schema before dispatch.
Verify a live connection with /mcp inside a session, or headlessly:
cmdc -p "usa la tool pvsyst entorno" --tools-all -t --yolo.
An empty value counts as unset, so the default or auto-detection applies.
Note on the workspace path. PVsyst 8 stores user data in
%USERPROFILE%\PVsyst8.1_Data(created on first run), not inDocuments\PVsyst8.1. The MCP auto-detects the real workspace and also accepts an explicitworkspaceargument on every tool. That argument moves the confinement root itself (every path check is relative to it), so it is a deliberate capability of this local server: only connect MCP clients you trust.
listar { "que": "modulos", "texto": "CX-M500" }
leer { "archivo": "CX-M500_2450Wp_1_00_086.PAN" }
→ { "format": "legacy-real48", "vendor": "Soitec", "pnom": 2450.0,
"voc": 695.7, "isc": 3.861, ... }
disenar_sistema { "latitud": 7.07, "longitud": -73.84, "kwp": 10,
"n_mod_serie": 10, "n_strings": 3 }
→ { "kpis": { "energia_producida_kwh": 15517, "produccion_especifica_kwh_kwp": 1567, "pr_pct": 83.0 },
"site": { "weather_source": "NASA SSE 6.0 grid cell 7/-74 ..." }, "pasos": [ ... ] }
proyecto { "accion": "crear", "plantilla": "_DEMO_Commercial",
"nombre_nuevo": "MY_VARIANT",
"modulo": "CX-M500_2450Wp_1_00_086.PAN" }
simular { "proyecto": "MY_VARIANT", "variante": "VC0",
"output_csv": "C:\\...\\Results\\out.csv",
"report_pdf": "C:\\...\\Results\\out.pdf" }
→ { "success": true, "stdout_tail": "... Simulation done in 0min 3sec ...", "costo": { ... } }
resultados { "que": "kpis" }
docs/pvsyst_format.md documents every file type observed from the outside,
including the recovered layout of the legacy binary .PAN (Delphi Real48,
50 × 6-byte slots) with the decoded field table. A standalone Python reference
decoder lives in tools/pan_decode.py.
PVSYST_CLI_REFERENCE.md is the exhaustive, verified reference for
PVsystCLI.exe (commands, exact option grammar, batch mode, success detection).
cargo test runs the unit tests and the end-to-end smoke tests in tests/mcp_smoke.rs, which drive the compiled server over stdio exactly like a client. Real-PVsyst tests skip when PVsyst is absent.leer decodes the bundled legacy CX-M500 module to PNom = 2450 W (exact), Voc = 695.7 V, Isc = 3.861 A.proyecto crear built a ~507 kWp variant; simular ran it at the new site with synthetic weather → Simulation done in 0min 2sec + PDF generated; resultados que:csv parsed the 330 KB CSV (8 760 hourly rows, date;GlobInc;GlobEff;EArray;E_Grid;PR).editar (fields), proyecto dimensionar and workspace restaurar are covered by smoke tests; history snapshots are checked via UserData/mcp_history/<id>/manifest.json.success:false), e.g. an over-sized array rejected by PVsyst with "array Voc … greater than the inverter absolute maximum input voltage".gui_observar que:ventanas|controles enumerated PVsyst's real VCL windows/controls; gui_actuar accion:click on the Herramientas button opened TToolsForm; gui_observar que:capturar produced a screenshot; gui_actuar accion:cerrar closed it. Covered by the gated test gui_invokes_button_and_opens_window.Every table, figure and report quoted above was produced with PVsyst 8.1.7 (PVsystCLI); see citation.
One folder per PVsyst business area; dependencies point inward to format/
(pure core, imports nothing from the crate). server/ (inbound) and
adapters/ (outbound) are the edges. tools/check_deps.py fails CI on any
cycle; the layering, bottom-up, is:
error → format, state → config → args → history → workspace →
adapters → feature modules (components, objects, projects, sites,
simulation, admin, prefs, easy_mode) → server
Every production source file in src/ stays under 300 lines; large areas are directory
modules split by concept. The two older end-to-end test suites (tests/mcp_smoke.rs and
tests/mcp_regresiones.rs) predate that limit.
src/
main.rs stdio entry point
config.rs workspace / CLI / GUI path resolution
state/ per-server registries (background jobs, UIA cache) and their records
args.rs tool-argument extraction (aliases, fail-fast errors)
server/ inbound adapter: MCP over stdio
mod.rs JSON-RPC / MCP protocol (newline-delimited, version negotiation)
tools/ one declaration per tool: schema + validation + handler (by family)
format/ core: PVsyst file formats (no I/O)
object.rs generic PVObject text parser (BOM-safe) + structural diagnostic
selector.rs strict object selector parser (`pvVCalcul/pvSubArray[1]`)
span.rs byte-preserving object span scanner
edit.rs / insert.rs / delete.rs field edits, object insert/extract, object removal
adapters/ outbound adapters to the PVsyst executables
cli/ PVsystCLI runner: capped capture, typed classification, background jobs
gui/ Win32 UI automation (windows, actions, waits, GDI capture with RAII, PNG)
uia/ UI Automation tree and element operations
history/ snapshots, validated restore, atomic writes (unique temp, per-path lock)
workspace/ path scope (`resolver_ruta`), bounded reads, guarded listing, writes
objects/ leer_objeto / listar_objetos / editar_objeto
projects/ listing, lifecycle/, doctor/, anadir/, temporales
components/ all component kinds; pan/ (Real48, strict legacy decoder), ficha/
sites/ sites, readers, NASA grids, solar/, pvgis/ (staged, transactional)
simulation/ preparation, execution, state, batch, cache/, results/, report_pdf/, engineering/
admin/ workspace/project/component import-export, licence, logs
prefs/ PVsyst.ini preferences and CLI log diagnostics
easy_mode/ disenar_sistema: typed per-step pipeline, diagnostico, leer_kpis
tests/mcp_smoke.rs end-to-end protocol tests
docs/pvsyst_format.md file formats (observed from outside)
docs/cobertura.md coverage map (area -> tool, GUI-only boundary)
docs/pvsyst_features.md full 623-page feature inventory
tools/pan_decode.py reference decoder
Yes. simular prepares the variant, shells out to the documented
PVsystCLI run-simulation command, parses the success markers and returns the KPIs —
no window is opened. The GUI tools (gui_observar, gui_actuar) exist for the dialogs
that have no file or CLI equivalent; they are available by default.
For headless simulation, yes. PVsystCLI runs in TRIAL mode without a licence
(evaluation limits apply, see responsible use);
the server tracks the remaining budget in a ledger, asks for confirmation before a run
that would spend several executions, and caches repeated simulations. File-level work —
listing, reading, editing, sites, sizing, component creation — needs no licence at all.
Anything that speaks MCP over stdio and reads the usual mcpServers map: Command Code,
Claude Desktop, Cursor, VS Code, and others. See
install into an MCP client. The server opens no network
port.
No. It is an unofficial interoperability project: no PVsyst code, no decompilation, no
redistribution of PVsyst software, and no licence management. PVsyst.exe is never
opened in a disassembler; PVsystCLI.exe is only run.
It edits only what you ask, at byte level, and refuses files whose PVObject structure
is unbalanced. Every write is preceded by a snapshot under UserData/mcp_history/<id>/,
and workspace accion:restaurar validates the whole manifest before writing anything
back. Note that PVsyst itself documents its file format as internal and unsupported, so
snapshots are the safety net, not PVsyst support.
No. The only outbound requests are the PVGIS calls you trigger: meteo_pvgis and, with
PVSYST_MCP_APROXIMACIONES=1, horizonte_pvgis and the optional fetch of
resultados que:p50_p90. Nothing is uploaded, and no telemetry is collected.
Yes: simular accion:ejecutar with filas runs a PVsyst batch (-bpf, one row per
orientation or configuration, each counting as one execution), simular accion:preparar writes
batch and parameter files, and long runs can be started
as background jobs polled with simular accion:estado.
.PAN modules?Yes. The legacy Delphi Real48 layout was recovered from the outside and is decoded by
components/pan/; tools/pan_decode.py is a standalone reference decoder you can run
without the server.
Defaults target PVsyst 8.1.7, with the executable and workspace paths configurable
through PVSYST_CLI, PVSYST_GUI and PVSYST_WORKSPACE. Supported artifacts include
.PRJ / .VCi projects and variants, .PAN (text and legacy binary) and .OND
components, .SIT sites, .MET weather files, plus raw PVObject text.
There is no public API to use. This project deliberately takes the two supported routes
— the documented PVsystCLI commands and the data files — instead of reimplementing a
simulation engine, which would give you different numbers than PVsyst.
This is an unofficial tool that drives your installation of PVsyst, so the terms that apply to the program are the ones you accepted when you installed it: PVsyst SA's General Conditions of Use and your subscription contract. How this project positions itself against them:
PVsyst.exe/PVsystCLI.exe; it reads and writes your data files and runs
the documented CLI.workspace argument plus permitir_fuera_del_workspace
give any connected client real filesystem reach.PVsystCLI explicitly may. That maps
to this project's surface: the CLI-based tools are fine on a server, the GUI tools
gui_observar / gui_actuar are not.entorno accion:licencia_activar merely prints the activation command for you to run
with your own key. The licence file, the registry and the system clock are never
written to.proyecto accion:doctor and
keep the snapshots.Clause 8.4 of the GCU requires quoting PVsyst whenever you publish images or tables
generated by it. Every result quoted in this repository — including the report fixture
in tests/fixtures/results/ — was generated with:
PVsyst 8.1.7 (PVsystCLI), PVsyst SA, Satigny, Switzerland — https://www.pvsyst.com
pvsyst-mcp itself is licensed under the Apache License 2.0 (LICENSE),
with the attribution notice in NOTICE. If you fork it or redistribute a
modified version you must keep the attribution notices and mark the files you changed
(sections 4(b)–4(d)), and section 6 grants no rights to the project name. Contributions
are accepted under the same licence — see CONTRIBUTING.md.
Issues and pull requests are welcome. Start with CONTRIBUTING.md for the ground rules (no vendor data in the repository, no decompilation, behaviour-based tests), the Code of Conduct, and SECURITY.md to report a vulnerability privately. Changes are tracked in CHANGELOG.md.
cargo fmt --check
cargo clippy --all-targets -- -D warnings # lints (unwrap/panic/unsafe docs/complexity/...) live in Cargo.toml + clippy.toml
cargo test # hermetic: synthetic workspace in tests/fixtures/workspace, no PVsyst needed
cargo test -- --ignored # also run the tests that need the PVsyst 8.1.7 demo data / a running GUI
cargo audit; cargo deny check # advisories, licences, bans, sources (deny.toml)
The crate is a library (pvsyst_mcp: Paths, Server, serve) plus a thin
pvsyst-mcp binary. Errors are typed (src/error.rs); logs go to stderr and are
filtered with PVSYST_MCP_LOG (default info) because stdout carries the protocol.
MCP server that automates PVsyst 8.1.7 through its data files and the documented PVsystCLI commands
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
PVSYST runs locally over stdio.
Last checked 2026-10-28. MCP server that automates PVsyst 8.1.7 through its data files and the documented PVsystCLI commands