Skip to main content

PVsyst CLI MCP

English | 简体中文

Local MCP server and Python adapter for driving an installed copy of PVsyst 8 on Windows. It wraps PVsystCLI.exe for simulations, weather conversion, and license checks, and provides headless parsers, zero-template synthesizers, diagnostics, TOU economics, bounded auto-optimization, and interactive Plotly HTML reporting across .PRJ, .VCx, .PAN, .OND, .BTR, .GEN, .SIT, and 3D .pvc2 shading scenes.

You need your own PVsyst installation and license on the host machine.

Common workflows

What you want to do Main entry point Guide
Run a zero-template fixed-plane or utility ground sheds/tracker PV design (mono/bifacial, finite 3D site_polygon + obstacles + base_slope_deg, optional auto-sizing) pvsyst_simulate_design, pvsyst_suggest_sizing Single-design inputs
Filter workspace/builtin components by electrical specs or synthesize custom .PAN/.OND (single- or 3-voltage) / Li-ion .BTR directly from datasheets (or refit .PAN single-diode params on STC edits) pvsyst_list_components, pvsyst_build_sourced_component, pvsyst_update_component Sourced components
Fetch hourly or TMY weather (Open-Meteo ERA5, PVGIS v5.3 TMY, NASA POWER) and optionally chain into .SIT/.MET preparation pvsyst_resolve_location, pvsyst_acquire_weather, pvsyst_prepare_weather Weather preparation
Run a parametric sweep (tilt, pitch, albedo, soiling, grid limit) in one CLI call and rank results pvsyst_run_batch_sweep Tool reference
Audit completed simulation CSVs (+ optional .VC0 attribution) and run a bounded Diagnose → Patch → Re-simulate loop on cloned variants pvsyst_diagnose_results, pvsyst_optimize_variant Tool reference
Plan TOU 2-charge/2-discharge PowerShift 48-slot schedules & run two-stage hybrid PV+BESS sizing optimization (fast grid sweep + optional Stage 2 PVsystCLI verification) pvsyst_plan_tou_storage_schedule, pvsyst_optimize_bess_sizing Tool reference
Evaluate fixed, TOU, and two-part demand-charge tariffs, battery replacement, sensitivity tornadoes, 25-year cashflows, LCOE, NPV, IRR, and payback pvsyst_evaluate_economics Tool reference
Run a one-shot end-to-end PV/PV+BESS feasibility study (synthesis → simulation/reuse → diagnostics → BESS sizing → economics → interactive Plotly HTML report) pvsyst_run_feasibility_study, pvsyst_generate_report, pvsyst_export_engineering_delivery Engineering delivery
Build a 3D house + obstacles scene, bind roof orientations, and run annual shading (linear or module_layout) pvsyst_run_house_task House task
Prepare hourly or sub-hourly (5/10/15/30 min) weather and evaluate AC-coupled storage pvsyst_prepare_weather, pvsyst_create_grid_storage_system, pvsyst_run_simulation Storage engineering
Inspect an existing project, apply an isolated revision, or diff multiple scenarios pvsyst_project_handoff, pvsyst_run_engineering_task, pvsyst_compare_engineering_scenarios Scenario comparison
Check feasibility briefs or block assembly (requires expert) pvsyst_review_engineering_brief, pvsyst_prepare_block_project Brief review

By default the server registers 46 core tools across 8 default groups. PVSYST_TOOL_GROUPS is an explicit group list: setting admin or expert alone replaces the defaults and exposes only that group. Set PVSYST_TOOL_GROUPS=all to expose all 75 tools; to keep the defaults and add expert, use setup,projects,components,weather,storage,simulation,results,engineering,expert. For migrating from v0.1.0, see Upgrading from v0.1.0.

Installation

Requirements:

  • Windows with Python 3.10+
  • Installed PVsystCLI.exe (tested against 8.0.6, 8.1.6 rev49278, and 8.1.7 rev49382)
  • Optional legacy GUI mode only (scene_import_method="gui"): PVsyst 8.1.6/8.1.7 GUI in Chinese locale at 96 DPI (100% display scaling); 3D house scenes, obstacles, module_layout, and DC cabling run headlessly without driving the desktop GUI by default

From the repository root:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
$env:PVSYST_CLI = 'C:\Program Files\PVsyst8.1.7\PVsystCLI.exe'
$env:PVSYST_WORKSPACE = 'C:\path\to\PVsyst8.1_Data'
.\.venv\Scripts\python.exe -m pvsyst_auto

Dependencies (mcp 2.x, pydantic 2.x, plotly for interactive HTML reports, and tzdata for Windows IANA timezones) are declared in pyproject.toml. Running pip install -r requirements.txt installs the same editable package; use pip install . for a regular install.

MCP client configuration

Point your MCP client at the virtualenv Python executable. Launching via -m pvsyst_auto (or the installed pvsyst-mcp console script) does not depend on the working directory:

{
  "mcpServers": {
    "pvsyst": {
      "command": "C:/path/to/pvsyst-cli-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "pvsyst_auto"],
      "env": {
        "PVSYST_CLI": "C:/Program Files/PVsyst8.1.7/PVsystCLI.exe",
        "PVSYST_WORKSPACE": "C:/path/to/PVsyst8.1_Data"
      }
    }
  }
}

pvsyst_mcp_server.py at the repo root is kept as a thin wrapper so older client configs still boot. Restart your MCP client after changing environment variables or pulling code updates.

Once connected, the server exposes MCP protocol instructions, 6 built-in workflow prompts (design_fixed_or_utility_pv, design_rooftop_3d_pv, design_pv_with_storage, diagnose_and_optimize_simulation, ci_bess_feasibility_study, optimize_bess_sizing), and 5 on-demand resources (pvsyst://guide/workflows, pvsyst://guide/variables, pvsyst://workspace/projects, pvsyst://workspace/components, pvsyst://workspace/results). Run pvsyst_capabilities and pvsyst_license_info first to confirm CLI flags and remaining license quota (note that PVsyst tracks CLI and GUI licenses separately; license mutation commands remain opt-in under admin).

Filtering exposed tool groups

By default (when PVSYST_TOOL_GROUPS is unset), the server exposes only the 46 core workflow tools (setup, projects, components, weather, storage, simulation, results, engineering) so LLM context stays compact. Set PVSYST_TOOL_GROUPS in env to customize; an explicit list replaces the defaults:

  • "PVSYST_TOOL_GROUPS": "all" exposes all 75 tools (the 8 default groups plus admin and expert).
  • "PVSYST_TOOL_GROUPS": "setup,projects,components,weather,storage,simulation,results,engineering,expert" keeps the defaults and adds expert (71 tools).
  • "PVSYST_TOOL_GROUPS": "setup,engineering,results" exposes only those 14 tools.
  • Valid group keys (case-sensitive): setup, projects, components, weather, storage, simulation, results, engineering, admin, expert (or all). Unknown, empty, or duplicate group names raise an error at startup so typos fail fast.

Understanding task statuses

High-level workflow tools return structured status fields so callers can tell the difference between a dry-run check, a file edit, and an actual PVsyst simulation:

Status / Flag What it means
ready Dry-run preflight passed; no files were written and PVsyst did not run
prepared Project or input files were written to disk, but no simulation has run yet
stage=completed + native_consumption_verified=true PVsyst ran the simulation and output checks (calendar, columns, units) passed
needs_review Simulation or preparation finished, but there are caveats to check (e.g. template-inherited fields, weather time-shift warnings, or missing engineering citations)
blocked / failed Preconditions or execution failed; check issues and any retained working files before retrying under a new output name

Package layout

src/pvsyst_auto/
├── api/          # MCP server setup, protocol guidance (prompts/resources), strict validation, 8 tool modules
├── workflows/    # End-to-end pipelines (design, utility 3D, batch sweep, optimize loop, house tasks, Plotly HTML report, ZIP delivery)
├── engineering/  # Sizing assistant, physics diagnostics, financial/TOU economics, handoff, brief checks, scenario comparison
├── project/      # .PRJ/.VCx parsing, zero-template synthesizer, pvBiFacial, circuits, templates, and orientations
├── components/   # .PAN/.OND/.BTR/.GEN store + mtime index cache, allowlisted editors, single-diode/Mode-1 datasheet synthesis
├── scene/        # PVCollada (.pvc2) 3D house mesh & finite 3D ground polygon clipper/shading builder
├── energy/       # Load profiles, AC-coupled battery storage, loss scalars, and power factor / grid limits
├── weather/      # Open-Meteo ERA5, PVGIS v5.3 TMY & NASA POWER downloaders, sub-hourly CSV & .SIT/.MET conversion
├── native/       # Subprocess wrapper for PVsystCLI.exe, headless 3D pvShading/module_layout emitter, and legacy Win32 bridge
└── results.py    # Result CSV parser and hourly/sub-hourly aggregation

See architecture.md for module responsibilities and old-to-new import paths, and native-entry-map.md for the support matrix across PVsyst features.

To use the CLI wrapper directly from Python:

from pvsyst_auto import PVsystCLI, PVsystError

Development & tests

Integration and unit test suites live under tests/integration/ and tests/unit/. See the testing and release guide for split test slices, CI verification, and release builds. Opt-in real-PVsyst tests live under tests/e2e/.

License

MIT.

Metadata

Release files for pvsyst-cli-mcp 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pvsyst-cli-mcp 0.5.0
File Size Uploaded Provenance Actions
pvsyst_cli_mcp-0.5.0.tar.gz 560.8 kB With provenance Details for pvsyst_cli_mcp-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pvsyst-cli-mcp 0.5.0
File Interpreter ABI Platform Actions
pvsyst_cli_mcp-0.5.0-py3-none-any.whl Python 3 none any Details for pvsyst_cli_mcp-0.5.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / pvsyst_cli_mcp-0.5.0.tar.gz

Download URL pvsyst_cli_mcp-0.5.0.tar.gz
Size 560.8 kB
Tags Source
SHA-256 checksum
How to use checksums
13f9b948c953c776017ff7659213a20941dd0822a70086100968dd5b4f4b7e00
BLAKE2b-256 checksum
How to use checksums
f52db9eb532847c5ee0ecc5edda53ba3eab4cbc164134b24ea630931a3862cd1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / pvsyst_cli_mcp-0.5.0-py3-none-any.whl

Download URL pvsyst_cli_mcp-0.5.0-py3-none-any.whl
Size 624.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91655ab4bd7a60685e0caa6c274c4c79fc30257d6876ff2fb6084a30b9ef78a1
BLAKE2b-256 checksum
How to use checksums
66826ff9ba4cd5076683b48e4b8a9d66a28213ec895ccb9cb184e278a9f04879
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for pvsyst-cli-mcp 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pvsyst_cli_mcp-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page