Aquamatrix SIMAR MCP Server
An async Model Context Protocol server exposing the read-only billing features of the Aquamatrix SIMAR 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.
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.
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 before changing the network exposure.
Run
For local MCP hosts, use stdio:
aquamatrix-simar-mcp
For a local HTTP client, use current Streamable HTTP:
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 Streamable HTTP is the current standard transport.
Configuration:
| Variable | Default | Description |
|---|---|---|
SIMAR_NIF |
Required | SIMAR account NIF |
SIMAR_PASSWORD |
Required | SIMAR account password |
SIMAR_BASE_URL |
https://www.aquamatrix.pt |
Portal base URL |
MCP_TRANSPORT |
stdio |
stdio or streamable-http |
MCP_HOST |
127.0.0.1 |
HTTP bind address; loopback only |
MCP_ALLOW_NON_LOOPBACK |
false |
Explicit opt-in to a non-loopback bind, intended for container networking |
MCP_PORT |
8000 |
HTTP port |
Development
python -m pip install -e '.[dev]'
pytest
ruff check .
mypy src
See PRD.md, ARCH.md, and AGENTS.md for scope, design, and contributor requirements.
Documentation
The documentation site includes installation, Docker Compose, security, and publishing guidance. GitHub Pages is built and deployed by GitHub Actions.
Author and license
Copyright (c) 2026 Oldemar Jesus oldemego@gmail.com. MIT licensed; see LICENSE.