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:

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.