Skip to main content
Glama
README.md
# aeat-mcp

An MCP server and background sync for the **[Agencia Tributaria (AEAT) sede electrónica](https://sede.agenciatributaria.gob.es)**. 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`](https://docs.astral.sh/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:
   ```sh
   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:
   ```sh
   uvx --from git+https://github.com/isdelrey/aeat-mcp aeat-mcp sync --no-notify --from-year 2022
   ```
5. **Register the MCP server:**
   - Claude Code:
     ```sh
     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:
     ```json
     { "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:
   ```sh
   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.

---

## 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](https://ntfy.sh) 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`.

## Related

- [dehu-mcp](https://github.com/isdelrey/dehu-mcp): official notifications (DEHú) from AEAT and every other administration. Use both together.

MIT licensed.