Skip to main content
Glama

aeat-mcp

An MCP server and background sync for the Agencia Tributaria (AEAT) sede electrónica. It logs in by itself with your digital certificate (.p12 / .pfx) and keeps track of:

  • Debts (Consulta de deudas): amount, voluntary vs. enforcement period (periodo voluntario / ejecutivo), status.

  • Payment plans (aplazamientos / fraccionamientos): every instalment, with due date, amount, and paid / pending / overdue.

  • Filed returns (declaraciones presentadas): 303, 130, 390, 100 (Renta), 111, 115, 347… for any year, with the receipt PDF, and whether each one is paid:

    • paid at filing (bank reference, NRC);

    • nothing to pay (a compensar / negative);

    • refund;

    • filed unpaid, then matched against current debts and plans.

  • Quarterly filing compliance: every quarter since you started, on time / late (by how many days) / missing, plus the next deadlines.

Then an AI assistant can answer questions like "Is anything unpaid?", "Which instalments are due this month, and from which account?", "Did I file all my 303s?" or "Show me my 2024 Renta." You also get alerts when debts, instalments or returns change.

Read-only: nothing here pays, files, or answers requerimientos. Unofficial; not affiliated with AEAT. Everything runs locally: your certificate, password and data never leave your machine, except to log in to the AEAT sede itself.


🤖 Install with an AI assistant

Paste this repo's URL into your AI coding assistant (Claude Code, Cursor, etc.) and ask it to install it. Instructions for the AI:

  1. Requirements: check that uv is installed (uv --version). If not, install it with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). A headless Chromium (about 100 MB, via Playwright) is downloaded automatically on the first sync. To pre-install it: uvx --from git+https://github.com/isdelrey/aeat-mcp playwright install chromium.

  2. Ask the user for the path to their certificate file (.p12 or .pfx, e.g. an FNMT certificado de persona física). Don't search their disk for it without asking.

  3. Register the certificate. It asks for the certificate password, which the user must type themselves. Never ask the user to paste the password into the chat. In Claude Code, tell the user to run it with the ! prefix so the prompt appears in their terminal:

    uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp setup --p12 "/path/to/certificate.p12"

    This stores the password in the OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service) and copies the certificate into the app's private data folder. Optional flags: --docs-dir (where receipt PDFs go; default ~/Documents/AEAT) and --profile <name> (several taxpayers).

  4. First import. Choose how far back to fetch filed returns; it takes a few minutes and doesn't fire alerts for existing items:

    uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp sync --no-notify --from-year 2022
  5. Register the MCP server:

    • Claude Code:

      claude mcp add --scope user aeat -- uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp serve
    • Other MCP clients (Claude Desktop, Cursor, …), in their JSON config:

      { "mcpServers": { "aeat": { "command": "uvx", "args": ["--from", "git+https://github.com/isdelrey/aeat-mcp", "aeat-mcp", "serve"] } } }
  6. Optional: background sync + alerts. Ask the user first, because it installs a recurring job:

    uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp install --hours 4

    On macOS this installs a launchd agent; on Linux/Windows it prints a cron line to add. For phone pushes, set AEAT_MCP_NTFY_URL=https://ntfy.sh/<long-random-topic> before running install.

  7. Verify: uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp status. The MCP tools appear after restarting the client or opening a new session.


Related MCP server: BeeL MCP server

What you get

MCP tools

Tool

What it does

certificate_status

Which certificate is configured, its expiry date, recent sync runs

sync_now

Logs in and refreshes now (from_year= to import older returns)

debts

Current debts (include_cleared also shows debts paid or cancelled since)

payment_plans

Every payment plan with every instalment: paid / pending / overdue

upcoming_payments

Instalments due in the next N days, and the bank account each is charged to

filed_returns

Returns filed, by modelo and year, with receipt path

payment_status

Per return: paid at filing, nothing to pay, refund, or unpaid with outstanding amount and plan progress. Also open debts

return_compliance

Quarterly modelos: every quarter on time / late / MISSING, plus the next deadlines

receipt_text

Text of a return's receipt PDF (shows all its boxes)

recent_changes

What's new since N hours ago

Alerts (macOS Notification Center or Linux notify-send, plus optional ntfy phone push):

  • a new debt, or a debt moving to the enforcement period (recargo de apremio);

  • an instalment paid, or still unpaid after its due date;

  • a return filed;

  • the certificate expiring within 60 days;

  • sync failing for more than 24 hours.

How it works

  • Debts and payment plans: plain HTTPS to www1.agenciatributaria.gob.es with TLS client authentication using your certificate, then HTML parsing.

  • Filed returns: that page is a ZK web app, so it uses headless Chromium (Playwright) with the same client certificate. Receipts are fetched through the CSV document check (cotejo).

  • Robustness:

    • every page must contain your NIF (a canary check);

    • a page that doesn't parse raises an error instead of being reported as "no data";

    • raw HTML of each sync is kept in the data folder, so the parser can be fixed if AEAT changes a page;

    • pop-up dialogs (alerts, "authorise SMS notices?") are closed without answering.

  • Certificate: decrypted in memory. A temporary PEM copy exists only during a sync, in a 0700 folder, and is deleted afterwards. Legacy FNMT .p12 files are supported.

  • State: SQLite in ~/Library/Application Support/aeat-mcp (macOS), %APPDATA%\aeat-mcp or ~/.local/share/aeat-mcp. The MCP server reads from it (fast, works offline). Only sync_now touches the network.

CLI

aeat-mcp setup --p12 FILE [--profile NAME] [--docs-dir DIR] [--password-stdin]
aeat-mcp sync [--from-year YYYY] [--no-returns] [--no-receipts] [--no-notify] [--profile NAME]
aeat-mcp status | mark-seen | install [--hours N] | uninstall | serve

Environment variables: AEAT_MCP_PROFILE, AEAT_MCP_HOME, AEAT_MCP_NTFY_URL, AEAT_MCP_P12_PASSWORD (headless servers without a keyring).

Which modelos and how many years are checked can be changed per profile in profiles.json (options.modelos, options.years_back). The default is the last 2 years plus the current one.

Notes and limits

  • Payment status of a return comes from its receipt and from the live debt list. A direct debit (domiciliación) shows as such until the charge appears.

  • Deadlines in return_compliance follow the standard calendar (20 Apr / 20 Jul / 20 Oct / 30 Jan), with weekend shifts approximated. Regional holidays aren't considered.

  • Updating: uvx --refresh --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp status.

  • dehu-mcp: official notifications (DEHú) from AEAT and every other administration. Use both together.

MIT licensed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides access to official Spanish fiscal data and tools based on AEAT and BOE sources, covering income tax, VAT, and regional deductions. It enables AI assistants to answer tax-related queries and verify filing deadlines using verified information.
      10
      32 npm
      13
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to issue, correct, and register legally compliant Spanish electronic invoices with AEAT VeriFactu, supporting F1/F2 types, R1–R5 correctives, and NIF validation from Claude, ChatGPT, Cursor, or VS Code.
      136
      142 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Chile's SII (Servicio de Impuestos Internos): connects Claude, Codex, Cursor and other MCP clients to your VAT (RCV, F29), income tax (F22), fee receipts (boletas de honorarios) and third-party statements, reconciles them and flags mismatches and deadlines. Read-only and local; the assistant never receives your password.
      15
      90 npm
      12
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to audit Spanish VERI*FACTU invoice chains and exported XML by recomputing AEAT fingerprints and verifying record links, generate AEAT tax QR codes and images, and build or validate Facturae 3.2.2 invoices offline. It also exposes helpers for NIF checks, QR URL checks, compliance deadlines, and credit balances.
      11
      154 PyPI
      Business Source 1.1