aeat-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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:
Requirements: check that
uvis installed (uv --version). If not, install it withcurl -LsSf https://astral.sh/uv/install.sh | sh(macOS/Linux) orpowershell -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.Ask the user for the path to their certificate file (
.p12or.pfx, e.g. an FNMT certificado de persona física). Don't search their disk for it without asking.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).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 2022Register the MCP server:
Claude Code:
claude mcp add --scope user aeat -- uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp serveOther 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"] } } }
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 4On 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 runninginstall.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 |
| Which certificate is configured, its expiry date, recent sync runs |
| Logs in and refreshes now ( |
| Current debts ( |
| Every payment plan with every instalment: paid / pending / overdue |
| Instalments due in the next N days, and the bank account each is charged to |
| Returns filed, by modelo and year, with receipt path |
| Per return: paid at filing, nothing to pay, refund, or unpaid with outstanding amount and plan progress. Also open debts |
| Quarterly modelos: every quarter on time / late / MISSING, plus the next deadlines |
| Text of a return's receipt PDF (shows all its boxes) |
| 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.eswith 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
0700folder, and is deleted afterwards. Legacy FNMT.p12files are supported.State: SQLite in
~/Library/Application Support/aeat-mcp(macOS),%APPDATA%\aeat-mcpor~/.local/share/aeat-mcp. The MCP server reads from it (fast, works offline). Onlysync_nowtouches 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 | serveEnvironment 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_compliancefollow 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.
Related
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
Spanish Veri*factu invoicing: create invoices, expenses and VAT returns from your AI assistant.
Run your rentals in Spain from your AI assistant: SES filings, VeriFactu invoices, rent, taxes.
Deterministic European sovereign engine with 90 tools across 20 vertical suites for AI agents: EU Tax/KYB, FatturaPA/Peppol, AI Act, GDPR, DORA, NIS2, Italian Tenders (D.Lgs 36/2023), CBAM, EUDR, and Labour Law. Zero-Data-Retention with verifiable SHA-256 PDF/A audit certificates.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides 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.1032 npm13MIT

BeeL MCP serverofficial
AlicenseAqualityBmaintenanceEnables 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.136142 npm2MIT- AlicenseAqualityBmaintenanceMCP 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.1590 npm12MIT
- AlicenseAqualityBmaintenanceEnables 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.11154 PyPIBusiness Source 1.1