Wafeq-MCP

# ohneben's Wafeq MCP

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ohneben-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/ohneben)

---

#### License & Checks

[![CI](https://github.com/ohneben/Wafeq-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/ohneben/Wafeq-MCP/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE.md)

#### MCP Registries

[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.ohneben%252Fwafeq-mcp%2Fversions%2Flatest&query=%24.server.version&prefix=v&label=MCP%20Registry&color=blue&logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ohneben%2Fwafeq-mcp/versions/latest)
[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/ohneben/wafeq-mcp)
[![Wafeq-MCP MCP server](https://glama.ai/mcp/servers/ohneben/Wafeq-MCP/badges/score.svg)](https://glama.ai/mcp/servers/ohneben/Wafeq-MCP)

Run your [Wafeq](https://www.wafeq.com/) books in plain language from AI assistants
like **Claude**, **Cursor**, and any other [MCP](https://modelcontextprotocol.io)
client.

This [Model Context Protocol](https://modelcontextprotocol.io) 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**:

| What you get | Why it matters |
| --- | --- |
| **All 251 endpoints, spec-driven** | Full coverage of invoices, bills, quotes, credit and debit notes, payments, banking, journals, payroll, projects, inventory and reports — nothing hand-picked or left behind. |
| **Nine safety categories, not four** 🟢 / 🟡 / 🟠 / 🔴 | A dozen of Wafeq's POSTs are not creates. Previews write nothing; ending an amortization early posts to the ledger with no undo; reporting an invoice to a tax authority leaves your organization permanently. Each gets its own banner instead of being lumped in with "create". |
| **Server instructions sent on connect** | The client is told how to read the safety banners and the handful of Wafeq conventions — date format, decimal separator, whole-period report ranges — up front, instead of discovering them by getting a call wrong first. |
| **Machine-readable MCP annotations** (`readOnlyHint`, `destructiveHint`) | Hosts that honor annotations (Claude included) can auto-trust the 98 read-only tools and demand confirmation before any of the 44 that delete or cannot be undone. |
| **Correct report parameters, per report** | Each of the four reports gets its own schema: balance sheet takes `date` + `period_count`; profit-and-loss and cash flow take `date_after` + `date_before`; trial balance takes `from_date` + `to_date`. Wafeq **silently ignores** misspelled query parameters, so a wrong name looks like a working call. |
| **Whole-period validation before sending** | Profit-and-loss and cash flow reject ranges that don't align to whole months or years. The server checks locally and replies with the nearest valid range instead of spending a round trip on an HTTP 400. |
| **Automatic idempotency keys** | Every one of the 146 write endpoints that supports `X-Wafeq-Idempotency-Key` gets a UUID v4 automatically, reused across retries — so a network hiccup can never duplicate an invoice. Supply your own to make a deliberate re-run safe too. |
| **File uploads that actually work** | `POST /files/` is multipart-only and `POST /files/raw/` needs a `Content-Disposition` header. Both are handled; you pass base64 content and a filename. |
| **Binary PDFs handled as bytes** | The nine PDF endpoints are base64-encoded into a small envelope with size and content type, instead of being read as text and corrupted. |
| **Automatic retries with backoff** | Transient `429` / `5xx` responses are retried with jittered exponential backoff, honoring `Retry-After` — with the same idempotency key, exactly as Wafeq's integration guide requires. |
| **Built-in rate limiting** | Self-throttles so a burst of tool calls doesn't trip a `429`. Wafeq publishes no numeric limit, so the default is deliberately conservative and configurable. |
| **Tenant verified at startup** | A Wafeq API key is organization-scoped. The server calls `GET /organization/` before serving and publishes the result on `/health`, so a mis-set key shows up as a name you can check rather than as writes against the wrong company's books. |
| **Two transports: stdio *and* Streamable HTTP** | Use it locally in Claude Desktop, or run one always-on server that any number of MCP clients reach over HTTP. |
| **Docker + docker-compose, health check, auto-restart** | `docker compose up` and it stays up, bound to localhost only. |
| **Optional bearer-token auth** on the HTTP endpoint | Put the server behind a shared secret the moment it's reachable beyond localhost. |
| **Your secrets never reach the model** | Credentials live in the server's environment and are injected on every request. The passthrough tool cannot override `Authorization` or point the credential at another host. |
| **Drop-in spec updates** | Wafeq ships a newer spec? Replace one file and rebuild — new endpoints become new tools automatically, no code changes. |

### How it compares

| Capability | **This project** | Generic OpenAPI→MCP wrapper\* |
| --- | :---: | :---: |
| All 251 Wafeq endpoints as tools | ✅ | ✅ |
| Per-tool safety category + banner | ✅ | ❌ |
| Tax-authority filing flagged as irreversible, not "create" | ✅ | ❌ |
| `readOnlyHint` / `destructiveHint` MCP annotations | ✅ | ➖ |
| Read-only fields stripped from create/update bodies | ✅ | ❌ |
| Duplicated enum prose compacted out of schemas | ✅ | ❌ |
| Correct, per-report date parameters | ✅ | ✅ |
| Whole-period range validated before sending | ✅ | ❌ |
| Automatic `X-Wafeq-Idempotency-Key`, stable across retries | ✅ | ❌ |
| Multipart + raw-binary file upload | ✅ | ➖ |
| Binary PDF responses base64-encoded, not mangled | ✅ | ➖ |
| Transaction dates recovered for journal line items | ✅ | ❌ |
| Automatic retries on `429` / `5xx` (honors `Retry-After`) | ✅ | ❌ |
| Client-side rate limiting | ✅ | ❌ |
| Organization identity verified at startup | ✅ | ❌ |
| `stdio` transport | ✅ | ✅ |
| **Streamable-HTTP transport** | ✅ | ➖ |
| **Docker + docker-compose**, health check, auto-restart | ✅ | ❌ |
| **Optional bearer-token auth** on the endpoint | ✅ | ❌ |
| License | MIT | varies |

<sub>\*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](./MIGRATION.md). "➖" = varies by tool / not guaranteed.</sub>

## 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
`$ref`s, 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](#get-your-api-credentials).
- **Docker** (Docker Desktop on macOS/Windows) for the quick start below — or
  **Node.js ≥ 20** to [run from source](#run-from-source-stdio-no-docker).

## Quick start (Docker)

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

```bash
cp .env.example .env
```

Then edit `.env` and set `WAFEQ_API_KEY`. If the server will be reachable beyond
localhost, set `MCP_SHARED_TOKEN` to a long random string as well.

**2. Start the server:**

```bash
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:**

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

```json
{
  "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"