Wafeq

ohneben's Wafeq MCP

License & checks

MCP registries

Run your Wafeq books in plain language from AI assistants like Claude, Cursor, and any other MCP client.

This Model Context Protocol server exposes the Wafeq Public API — all 251 endpoints, generated straight from the OpenAPI spec into MCP tools, plus two hand-written ones. Every tool carries a safety category (🟢 read-only / 🟡 write / 🟠 state change / 🔴 irreversible or destructive) so your assistant knows what an action does *before* it calls it — including the difference between saving an invoice and filing it with a tax authority, which no CRUD-shaped wrapper can tell you. It runs over stdio (Claude Desktop and other local launchers) or Streamable HTTP (hosted in Docker), and ships with retries, client-side rate limiting, request timeouts, idempotency keys, multipart upload and binary PDF handling so it holds up against a live book.

Why you'll want this

Some MCP servers just forward an API. This one is built to be safe to hand to an LLM and easy to run against real accounting data:

How it compares

\*Generic OpenAPI→MCP wrappers turn any spec into MCP tools. They can reach the same endpoints, but treat every operation identically — and against Wafeq's spec specifically they inherit the read-only-required-field problem described in MIGRATION.md. "➖" = varies by tool / not guaranteed.

What you can do

Once it's connected, ask your assistant things like:

• "What was our profit and loss for the first half of this year?"
• "Show me every unpaid invoice older than 30 days, with the customer name."
• "Create a draft invoice for Acme Ltd for 3 days of consulting at €800/day."
• "Download invoice INV-2026-014 as a PDF."
• "Which account did the €7,000 transfer in January post to?"
• "Attach this receipt to expense EXP-118."
• "Reconcile the bank statement lines for March against the ledger."
• "Convert quote QUO-31 to an invoice and record the payment."

How it works

Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  Wafeq API (your organization)

At startup the server parses the bundled OpenAPI spec into MCP tools — resolving $refs, guarding against recursive schemas, and stripping server-assigned (readOnly) fields out of request bodies — tags each tool with its safety category, verifies which Wafeq organization the credentials belong to, and then injects your credential on every outgoing request. Your key stays in the server's environment; the model never sees or handles it.

Requirements

• A Wafeq organization with API access — either a private API key (Wafeq → Settings → Developer → API keys) or an OAuth2 access token. See Get your API credentials.
• Docker (Docker Desktop on macOS/Windows) for the quick start below — or Node.js ≥ 20 to run from source.

Quick start (Docker)

1. Add your credentials. Copy the example config and fill it in:

cp .env.example .env

Then edit .env and set WAFEQ_API_KEY. Unless HOST is a loopback address the server also requires MCP_AUTH_TOKEN and refuses to start without one, so set it to a long random string: MCP_AUTH_TOKEN=$(openssl rand -hex 32).

2. Start the server:

docker compose up -d --build

docker-compose.yml binds to 127.0.0.1:8765 only, so the server is reachable from your machine but not from the network.

3. Confirm it's running — and that it's pointed at the right books:

curl -s http://localhost:8765/health

{

"status": "ok", "server": "wafeq-mcp", "version": "2.0.0", "tools": 253, "organization": { "status": "ok", "id": "org_...", "name": "Your Company FZCO", "base_currency": "EUR", "country": "AE" }, "auth_required": false }

Check the `name` field. That is the organization your key writes to. If it isn't the company you expected, stop and fix the key before doing anything else. /health answers 503 and "status": "degraded" when the credentials can't be verified.

4. Point your MCP client at it: http://localhost:8765/mcp (Streamable HTTP).

Remote endpoints are added to Claude as a custom connector (Settings → Connectors), or bridged locally with mcp-remote. For the bridge, add this under mcpServers in your client config and restart the app completely:

{

"mcpServers": { "wafeq": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8765/mcp", "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN" ] } } }

(Drop the --header line only if the server runs without a token, which it allows on a loopback bind alone.)

Prefer a ready-made image?

Every release publishes a ready-to-run image to the GitHub Container Registry, so you can skip the local build entirely:

docker run -d --name wafeq-mcp -p 127.0.0.1:8765:8765 --env-file .env \

ghcr.io/ohneben/wafeq-mcp:latest

Pin a version (:2.0.0) rather than latest if you want releases to be something you opt into.

Install from the MCP Registry

The server is published to the MCP Registry as io.github.ohneben/wafeq-mcp, so registry-aware clients can install it by name. The registry entry launches the image over stdio — see Run the container over stdio for the equivalent hand-written config.

curl -s "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ohneben%2Fwafeq-mcp/versions/latest"

Get your API credentials

Private API key (most people): in Wafeq, go to **Settings