# SCAU Electricity MCP Server

[简体中文](README.zh-CN.md) | English

A lightweight, read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for querying dormitory electricity data at South China Agricultural University (SCAU).

The server runs locally over stdio, keeps authentication sessions in memory, and does not read Home Assistant configuration or persist tokens, cookies, room details, or query results.

## Features

- Query total and per-day electricity usage for an inclusive date range.
- Read the current electricity balance, refresh time, and meter status.
- Read lifetime electricity usage without supplying any parameters.
- Calculate range and daily electricity costs using a configurable unit price.
- Expose read-only, idempotent MCP tools with structured JSON results.

## Available tools

| Tool | Parameters | Description |
| --- | --- | --- |
| `get_daily_energy` | `start_date`, `end_date` | Returns total usage and per-day readings for an inclusive date range. |
| `get_balance` | None | Returns the current balance, refresh time, and meter online status. |
| `get_lifetime_energy` | None | Returns cumulative electricity usage since the meter came online. |
| `get_electricity_summary` | `start_date`, `end_date` | Returns range totals, daily readings and costs, lifetime usage as of the end date, and the current balance. |

Dates must use the `YYYY-MM-DD` format. `start_date` must not be later than `end_date`.

## Requirements

- Python 3.12 or newer
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- Network access to `http://cz.scau.edu.cn`
- Your SCAU electricity room name and room ID

## Installation

```powershell
git clone https://github.com/xnbx2012/scau-electricity-mcp.git
cd scau-electricity-mcp
uv sync
```

If `uv` reports `invalid peer certificate: UnknownIssuer` behind a system or corporate certificate proxy, run `uv --system-certs sync`.

## Running locally

Pass the room settings as command-line arguments:

```powershell
uv run python server.py --room-name "Your room name" --room-id "Your room ID"
```

Or use environment variables:

```powershell
$env:SCAU_ROOM_NAME = "Your room name"
$env:SCAU_ROOM_ID = "Your room ID"
uv run python server.py
```

The process communicates over stdio. It is normal for it to remain running without printing a prompt.

## MCP client configuration

Replace the directory with the absolute path to your clone:

```json
{
  "mcpServers": {
    "scau-electricity": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\scau-electricity-mcp",
        "run",
        "python",
        "server.py"
      ],
      "env": {
        "SCAU_ROOM_NAME": "Your room name",
        "SCAU_ROOM_ID": "Your room ID"
      }
    }
  }
}
```

If the client cannot find `uv`, set `command` to the absolute path of `uv.exe`. Do not commit client configuration containing real room details to a public repository.

## Configuration

| Environment variable | CLI option | Default | Description |
| --- | --- | --- | --- |
| `SCAU_ROOM_NAME` | `--room-name` | Required | Electricity account room name. |
| `SCAU_ROOM_ID` | `--room-id` | Required | Electricity account room ID. |
| `SCAU_BASE_URL` | `--base-url` | `http://cz.scau.edu.cn` | Upstream service URL. |
| `SCAU_DB_ID` | `--db-id` | `9853` | Upstream meter database ID. |
| `SCAU_ELECTRICITY_PRICE` | `--electricity-price` | `0.63` | Electricity price in CNY per kWh. |

Command-line options take precedence over environment variables.

## Development

```powershell
uv sync --group dev
uv run ruff check .
uv run pytest
```

Tests do not contact the university service and contain no real room information.

## Privacy and security

- Room details are sent only to the university electricity service.
- Authentication tokens and cookies remain in memory and are not persisted.
- The upstream service currently uses plain HTTP, so traffic is not protected by TLS.
- All exposed MCP tools are read-only.

## Disclaimer

This is an unofficial community project and is not affiliated with or endorsed by South China Agricultural University. The upstream interface may change without notice.

## License

Licensed under the [MIT License](LICENSE).