aquamatrix-simar-mcp

# Aquamatrix SIMAR MCP Server An async Model Context Protocol server exposing the read-only billing features of the [Aquamatrix SIMAR Python SDK](https://github.com/OldemarJesus/aquamatrix-python-sdk). Unofficial and not affiliated with SIMAR or Aquamatrix. ## Tools - `get_invoices`: fetch one page of invoice history with optional date filtering. - `get_pending_invoices`: list invoices the SDK recognizes as unpaid. - `get_billing_summary`: return the portal's invoice-to-pay and failed-invoice counts. All tools are read-only. Invoice amounts are returned as decimal strings; dates use ISO `YYYY-MM-DD` strings. Credentials are supplied only through the server process environment, never through tool calls. ## Requirements and installation - Python 3.14 or newer. - A SIMAR portal account. ```shell python -m pip install aquamatrix-simar-mcp ``` Set `SIMAR_NIF` and `SIMAR_PASSWORD` in the MCP server process environment. Optionally set `SIMAR_BASE_URL` when using a compatible portal host. ## Docker Compose The Compose example runs Streamable HTTP inside a container and publishes it only on host loopback. Set credentials in the process environment or an ignored `.env` file; do not commit secrets. ```shell export SIMAR_NIF='your-nif' export SIMAR_PASSWORD='your-password' docker compose up --build -d ``` The MCP endpoint is `http://127.0.0.1:8000/mcp`. Set `MCP_PORT` to change the port. The container opts into `0.0.0.0` only within its network namespace; Docker's host-side port binding remains `127.0.0.1`. See the [container guide](docs/guide/docker.md) before changing the network exposure. ## Run For local MCP hosts, use stdio: ```shell aquamatrix-simar-mcp ``` For a local HTTP client, use current Streamable HTTP: ```shell MCP_TRANSPORT=streamable-http aquamatrix-simar-mcp ``` The HTTP server binds to `127.0.0.1:8000` by default. It has no HTTP authentication; do not expose it directly to an untrusted network. SSE is intentionally not provided because Strea…