DEV Community

Cover image for I built an MCP server that tells you why the AEAT rejected your Odoo invoices
Juan Cantón Rodríguez
Juan Cantón Rodríguez

Posted on

I built an MCP server that tells you why the AEAT rejected your Odoo invoices

Spain is about to make every invoice talk to the tax agency. With Veri*Factu, each invoice a company issues is sent to the AEAT as a signed, chained record, with a QR code on the paper. Companies start on 1 January 2027 and everyone else on 1 July 2027. The government has announced a delay to 2028, but as I write this it is not in the official gazette, so the legal dates are still the 2027 ones. The larger companies already report every invoice through SII, which is the older system and exempts them from Veri*Factu.

Odoo handles both. What it doesn't do is answer the questions an accountant actually asks at the end of the quarter:

  • Which invoices did the AEAT reject this quarter, and why?
  • Which ones were never sent?
  • When does our certificate expire?
  • How much output and input VAT do we have, by tax?

In Odoo you open invoices one by one, or build a filter, or export to a spreadsheet. So I wrote a small MCP server that lets Claude (or any MCP client) answer them directly: odoo-verifactu-mcp. It's open source (MIT) and read-only. It never sends, cancels or changes anything.

Two families of modules, one set of answers

The first surprise was that "Veri*Factu in Odoo" means two different things.

Odoo S.A. OCA (l10n-spain)
Veri*Factu l10n_es_edi_verifactu l10n_es_verifactu_oca
SII l10n_es_edi_sii l10n_es_aeat_sii_oca
Where the state lives its own field on the invoice, plus a history model one shared aeat_state for both

They even name things differently. Odoo calls it registered_with_errors, the OCA calls it sent_w_errors. A rejection is rejected in one and incorrect or cancel_incorrect in the other. Odoo's SII state is computed and not stored, so you can't filter on it at all; you have to go through its document model.

In Spain a lot of integrators run the OCA modules, so supporting only one family would leave half the market out. The server detects which modules are installed (by asking fields_get on account.move) and maps both to the same six states: pending, accepted, accepted_with_errors, rejected, invalid and cancelled. Whoever asks gets the same answer either way.

Six tools

  • compliance_overview: installed modules, how each company is set up (test or production), certificates and the days they have left, and invoice counts by state. Start here.
  • verifactu_invoices: invoices with their Veri*Factu state, the AEAT CSV and the last error.
  • verifactu_errors: errors of the period grouped by message, with sample invoice numbers. This is the most useful one: "[4102] El XML no cumple el esquema" on twelve invoices is one problem to fix, not twelve.
  • sii_invoices: the same for SII, issued and received.
  • invoice_aeat_detail: one invoice, its QR URL, every submission and every error.
  • vat_summary: VAT by tax for the quarter, a working aid before filing form 303.

Two things I only learned by testing against real databases

Exempt taxes don't create tax lines. My first VAT summary added up the tax lines, which is the obvious approach. Odoo's demo company for Spain invoices with a 0 % exempt tax, and a 0 % tax creates no tax line at all, so its whole base vanished from the summary. For a form 303 the exempt base matters. The fix: take the base from the lines that carry each tax, and the amount from the tax lines. Checked to the cent against the journal items.

Some OCA fields fail when you read them. Unit tests against a simulated Odoo all passed. Then I spun up Odoo 18 with the real OCA modules, one company on Veri*Factu and one on SII, and asked for the detail of a vendor bill from the SII company. Odoo answered with an error: 21% G tax is not mapped to VERI*FACTU. The OCA module computes some Veri*Factu fields when you read them, and on an invoice that isn't Veri*Factu that computation raises. Now the server first reads which regime applies to the invoice and only then asks for that regime's fields. A mock would never have told me that.

Odoo 16 to 20

Odoo 19 introduced a new external API, JSON-2: POST /json/2/<model>/<method> with the API key as a bearer token and named arguments. Older versions use JSON-RPC with execute_kw. The client picks one from the server version, and since both take named arguments the rest of the code doesn't care. It's tested on Odoo 20 over both, and on Odoo 18 with the OCA over JSON-RPC.

Try it

Create an API key in Odoo (Preferences → Account Security → New API Key) for a user who can read Accounting, then:

claude mcp add odoo-verifactu \
  -e ODOO_URL=https://mycompany.odoo.com \
  -e ODOO_API_KEY=your-api-key \
  -- npx -y @francodesystems-npm/odoo-verifactu-mcp
Enter fullscreen mode Exit fullscreen mode

On Odoo 16-18 also set ODOO_DB and ODOO_USERNAME. Then ask something like "¿Qué facturas ha rechazado la AEAT este trimestre y por qué?".

If you run the OCA modules and see something odd, an issue on the repo is very welcome.


I'm Juan, and I run Francodesystems, an Odoo implementation and integrations studio in Barcelona. There's a Spanish page for the server with a worked example of a quarter-end check, and if you want the regulatory side (the dates, who is affected, and what Odoo brings out of the box), I keep it up to date at Verifactu in Odoo.

Top comments (1)

Collapse
 
aichiliai profile image
AI Chili •

Domain-specific diagnostic MCP tools like this are where agents shine most: turning cryptic XML/schema validation failures into structured, actionable fixes right inside the conversation.