Skip to main content
Glama
PLENTICORE MCP

PLENTICORE MCP

by NemoN

PLENTICORE MCP

CI License: MIT

English · Deutsch

An MCP server for KOSTAL PLENTICORE inverters. Read power, energy counters and events, inspect settings, and change settings available to the plant owner. The server connects to the inverter's local REST API using pykoplenti and the official MCP Python SDK.

Tested with a PLENTICORE plus 8.5 running firmware 01.30.12092, API 0.2.0. Other models and firmware versions have not been tested. Available measurements and settings are discovered from the connected device.

Quick start

Install uv and Python 3.11 or newer, then clone the repository:

git clone https://github.com/NemoN/plenticore-mcp.git
cd plenticore-mcp
uv sync --frozen
cp .env.example .env
chmod 600 .env

Edit .env with your inverter's address and the plant owner password from its local web interface:

PLENTICORE_URL=http://plenticore.example
PLENTICORE_PASSWORD=replace-locally
PLENTICORE_TIMEOUT=20
PLENTICORE_VERIFY_SSL=true
PLENTICORE_READ_ONLY=true

Use the base URL without /api/v1. The example starts in read-only mode. Set PLENTICORE_READ_ONLY=false when you want to apply settings changes. If omitted, the code default is false; update calls still preview by default.

Check the login and current readings:

uv run --frozen plenticore-mcp --check

The check reads status and measurements without changing device settings. Exit code 0 means success; 1 indicates a connection or API error; 2 indicates invalid configuration. Starting without --check waits for an MCP client.

Related MCP server: tesla-powerwall

Connect an MCP client

For clients using mcpServers JSON, replace the two absolute paths:

{
  "mcpServers": {
    "plenticore": {
      "command": "uv",
      "args": [
        "run", "--frozen", "--directory", "/absolute/path/plenticore-mcp",
        "plenticore-mcp", "--env-file", "/absolute/path/plenticore.env"
      ]
    }
  }
}

The env file can be the checkout's .env or a separate private file. If the client cannot find uv, use its full executable path. The client starts the stdio process when needed. Standard output is reserved for the MCP protocol.

examples/ contains JSON and Codex TOML configurations. See configuration for environment variables, HTTPS and remote connections.

Streamable HTTP

uv run --frozen plenticore-mcp --transport streamable-http --port 8001

Connect to http://127.0.0.1:8001/mcp. The listener binds to loopback and has no MCP authentication. Use an SSH tunnel for access from another machine.

Tools

All names start with plenticore_. The tool reference lists their arguments and defaults.

Tool, without prefix

Purpose

status

API and firmware versions, session status, read-only mode

list_modules

Modules offered by the inverter

list_process_data

Search measurement IDs, with pagination

read_process_data

Read selected measurements

overview

Power flow, AC, PV strings, battery and grid meter, where available

battery

Battery-related readings, where available

energy

Energy statistics for Day, Month, Year or Total

events

Recent events in German or English

list_settings

Setting IDs, types, units, access rights and bounds

read_settings

Read selected current settings

update_settings

Preview changes, or write and read them back

Example requests for a connected assistant:

Show today's yield, this month's yield and the current AC output.

List the battery settings and their current values. Prepare a preview of the change I request before applying it.

Readings and units

Values and signs are returned as supplied by the inverter. Some firmware sends an empty unit; an empty unit does not mean that the value is dimensionless. Dc_P can include battery power. Use the individual PV string measurements when you need solar input power.

Energy periods follow the inverter clock. The server has no historical database or arbitrary date-range query. Missing measurements appear under missing; non-finite numeric values become JSON null. A battery-related data point does not establish that a physical battery is installed.

Settings changes

Read list_settings and read_settings before changing a value. Pass setting values as strings in the inverter's native units. update_settings defaults to dry_run=true and returns the current and proposed values. Set dry_run=false to submit the change and read it back.

The server checks advertised access rights, supported data types and numeric bounds. It rejects unknown IDs, unsupported types and write-only settings. Password and token settings recognized by their IDs are excluded. The inverter enforces the plant owner's permissions; installer access is not implemented.

Writes are not atomic. A failed request may leave some changes applied. Read the current settings before retrying. The result reports verification as matched, mismatch or unavailable; it does not perform an automatic rollback. PLENTICORE_READ_ONLY=true blocks writes while allowing previews.

See SECURITY.md for access and reporting details.

Docker

docker build -t plenticore-mcp .
docker run --rm -i --env-file .env plenticore-mcp

Use -i without -t for stdio. The inverter must be reachable from the container. The image runs as an unprivileged user and installs hashed runtime dependencies from requirements.lock. No prebuilt container image is published.

Development

uv sync --frozen
uv run --frozen pytest -q
uv run --frozen ruff check src tests scripts
uv run --frozen ruff format --check src tests scripts
uv run --frozen python scripts/generate_tool_reference.py --check
uv build
uv run --frozen python scripts/check_artifacts.py dist/*.whl dist/*.tar.gz

Tests use a local inverter emulator, including the login handshake, and real MCP stdio and HTTP connections. They do not require a physical inverter. Live validation covered all eleven tools; the update tool was tested as a preview. Actual writes and readback failures have been tested against the emulator only.

See CONTRIBUTING.md and CHANGELOG.md.

Project information

MIT licensed. Independent project, not affiliated with KOSTAL Solar Electric. Report reproducible problems through GitHub Issues. Remove credentials and identifying device details from reports and logs.

Available Tools

11 tools
plenticore_batteryA
Read-onlyIdempotent

Read available battery measurements, including SoC and power.

Inputs: no named parameters. Returns: object

plenticore_energyB
Read-onlyIdempotent

Read inverter-native energy counters for Day, Month, Year or Total. Preserve units.

Inputs: period. Returns: object

plenticore_eventsA
Read-onlyIdempotent

Read the latest 1–100 inverter events; active events may have end_time=null.

Inputs: limit, language. Returns: object

plenticore_list_modulesA
Read-onlyIdempotent

Discover the modules actually offered by this inverter and current user.

Inputs: no named parameters. Returns: object

plenticore_list_process_dataB
Read-onlyIdempotent

Discover measurement IDs. Search module/ID; follow next_offset for more.

Inputs: limit, query, offset. Returns: object

plenticore_list_settingsB
Read-onlyIdempotent

Discover setting types, units, access rights and min/max. Secrets are omitted.

Inputs: limit, query, offset. Returns: object

plenticore_overviewB
Read-onlyIdempotent

Read power flow, AC, PV strings, battery and meter measurements that exist.

Inputs: no named parameters. Returns: object

plenticore_read_process_dataA
Read-onlyIdempotent

Read explicit {moduleid: [IDs]} (max 200), returning native values and units.

Inputs: selection (required). Returns: object

plenticore_read_settingsA
Read-onlyIdempotent

Read explicit {moduleid: [setting IDs]}. Discover IDs first; secrets are excluded.

Inputs: selection (required). Returns: object

plenticore_statusA
Read-onlyIdempotent

Read API/firmware version and plant owner session status.

Inputs: no named parameters. Returns: object

plenticore_update_settingsA
Destructive

Preview settings changes; dry_run=false writes and reads back. Values are strings.

Uses actual owner-accessible IDs, types and min/max. No installer login. Read list_settings and the current values first. Multi-setting writes are not atomic; no automatic rollback. A connection error after submission can leave a change applied: read back before retrying.

Inputs: values (required), moduleid (required), dry_run. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 11 tools

    Disambiguation4/5

    The list_* discovery tools are clearly separated from the read_* tools by description (discover IDs vs read explicit IDs), and battery/energy/events/status each target distinct data. The only soft overlap is plenticore_overview, which aggregates battery, PV, meter and AC readings that plenticore_battery and plenticore_energy also expose, so an agent may occasionally choose overview redundantly.

    Naming Consistency4/5

    All names use a consistent plenticore_ prefix with snake_case, and the list_/read_/update_ verb pattern is applied predictably to processes and settings. The single-word resource reads (battery, energy, events, overview, status) deviate from the verb_noun pattern but remain unambiguous.

    Tool Count5/5

    Eleven tools is well within the ideal range for an inverter integration and each earns its place: discovery, targeted reads, an aggregate overview, and a single guarded write path. Nothing appears padded or redundant enough to be dropped.

    Completeness4/5

    The surface covers discovery, reads of measurements/energy/events/status, and settings read plus a dry-run-first write, which is a full lifecycle for this domain. Minor gaps exist: no process-data write, no setting pagination noted, and no explicit way to acknowledge or clear events, though these may be limitations of the inverter API.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides access to Alpha ESS solar inverter and battery system data, enabling monitoring of energy statistics, real-time power data, and configuration of battery charging and discharge schedules through the Alpha ESS Open API.
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides real-time access to solar inverter data from the SolaX Cloud API, enabling queries of power output, energy yields, battery status, and grid import/export data.
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to monitor and control Growatt solar installations via the ShineServer API, including reading PV generation, load, grid import/export, battery SOC, and adjusting inverter settings.
      26
      MIT