unofficialzaptecMCP

An unofficial MCP (Model Context Protocol) server that connects a Zaptec EV charger (Zaptec Go, Go 2, Pro) to AI assistants like Claude. Ask for the charging status, energy and cost of the last month, pause or resume a session, or lower the available current, all through natural conversation.

This project is not affiliated with, endorsed by, or sponsored by Zaptec AS. "Zaptec" is a trademark of Zaptec AS; it is used here only to describe what the server connects to.

Disclaimer: The server talks to the public Zaptec cloud API (api.zaptec.com) with your own Zaptec account. Only documented endpoints are used, but Zaptec may change the API at any time. Three tools change the state of your installation. Use at your own risk.

Features

Not included on purpose: restarting the charger, firmware upgrades, deauthorizing sessions, the undocumented authorizecharge call, local settings and OCPP.

Related MCP server: OCHP MCP Server

Prerequisites

• A Zaptec account with owner rights on the charger (the same login as the Zaptec app).

• Python 3.10 – 3.14.

• Claude Desktop or any other MCP-compatible client.

Installation

git clone https://github.com/holger1411/unofficialzaptecMCP.git
cd unofficialzaptecMCP
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

cp .env.example .env
# edit .env and set ZAPTEC_USERNAME and ZAPTEC_PASSWORD

The charger PIN printed on the device is not needed. It is only used by the Zaptec app for activation and local Bluetooth setup.

Claude Desktop

Add to your claude_desktop_config.json (see claude_desktop_config_snippet.json for a template):

{
  "mcpServers": {
    "unofficial-zaptec-mcp": {
      "command": "/absolute/path/to/unofficialzaptecMCP/.venv/bin/python",
      "args": ["-m", "zaptec_mcp_server"],
      "env": {
        "ZAPTEC_USERNAME": "your-email@example.com",
        "ZAPTEC_PASSWORD": "your-password",
        "ZAPTEC_PRICE_PER_KWH": "0.30"
      }
    }
  }
}

Restart Claude Desktop afterwards. Example prompts: "Is my car charging?", "How much did charging cost in September?", "Pause charging", "Limit the wallbox to 10 amps until I say otherwise".

Behaviour and limits

• Authentication: OAuth2 password grant against api.zaptec.com. The token is cached until shortly before it expires and refreshed once on a

  401. Zaptec allows one token request per second per IP, so the server never logs in per request.

• Rate limits: Zaptec allows 10 requests per second per user. Every request carries a descriptive User-Agent as required by Zaptec's fair-use policy. Transient errors (timeouts, 5xx, 429) are retried three times with backoff, honouring Retry-After.

• Caching: status 15 s, installation 5 min, history 5 min. Control tools are never cached and invalidate the status cache. Failures are never cached.

• Guards: pause and resume check the live charger state first and refuse with a plain-language reason when the command would be rejected. zaptec_set_available_current validates against the installation maximum and enforces the 15-minute spacing Zaptec recommends (per server process).

• History uses /api/sessions/archived, converted to the installation's timezone. Cost is energy_kwh × ZAPTEC_PRICE_PER_KWH, nothing more.

• Logging goes to stderr through a redactor that scrubs credentials, bearer tokens, UUIDs and device serials.

Security

See SECURITY.md. Never commit .env. Report security issues via GitHub Private Vulnerability Reporting, not as public issues.

Development

pip install -e '.[dev]'
pytest                    # unit tests, offline
ruff check .
mypy
pytest -m integration     # live read-only tests, needs .env
python scripts/probe.py   # prints the live status; --dump DIR writes raw responses

Fixtures under tests/fixtures/ are sanitized live responses. Capture new ones with scripts/probe.py --dump and run them through scripts/sanitize_fixture.py before committing; see CONTRIBUTING.md.

Credits

• Zaptec for the public API and its documentation at docs.zaptec.com. The OpenAPI spec is available at api.zaptec.com/swagger/v1/swagger.json; it is not redistributed in this repository.

• custom-components/zaptec and pyzaptec (MIT), whose observation and command handling served as reference.

• Model Context Protocol.

• holger1411/unofficialMCP4Vaillant and holger1411/polestar-mcp, the pattern references for the client, cache and test layout.

License

MIT. The license covers this project's code only. "Zaptec" and related names and logos are trademarks of Zaptec AS; they are used here only to describe compatibility. The software is provided "as is", without warranty of any kind. You use it at your own risk, including any effect on your charger, installation or electricity bill.