Skip to main content
Glama

mcp-invoices-pt

Invoice bookkeeping for freelancers in Portugal, done with an AI assistant.

You keep downloading invoices and receipts as you do today. Then you ask your assistant "organize my receipts", and it:

  • reads each document,

  • files it in a folder per tax year, under a consistent name,

  • books it in an Excel workbook (or a Google Sheet, if you prefer),

  • works out what goes into each box of the quarterly IVA return (Declaração Periódica), including the credit carried over from the previous quarter,

  • keeps the totals you need for IRS and the quarterly Segurança Social declaration,

  • and tells you what is still missing.

Technically it is an MCP server: a set of tools that an AI assistant such as Claude runs on your computer.

WARNING

No guarantee, and not tax advice. I do not guarantee that this software, or any figure it produces, is correct, complete or up to date with Portuguese tax law. It can misread a document, pick the wrong VAT treatment or put a value in the wrong box. Nothing here is tax, legal or accounting advice.

You are responsible for what you submit to the Autoridade Tributária. Check every figure against your documents before you file, and ask a certified accountant (contabilista certificado) when in doubt. I accept no liability for any loss, penalty or interest that results from using it. See also the License.

Updated regularly. New invoice and receipt layouts are added as they come up. See Supported documents and the CHANGELOG. If yours is not read yet, open an issue with a redacted sample, or add it yourself.


Contents

  1. Quick start

  2. Who it is for

  3. Supported documents

  4. How it reads documents

  5. Your folders and books

  6. Setup in detail

  7. Day-to-day use

  8. Tools reference

  9. Safety

  10. Privacy: public code, private data

  11. Adding a document type

  12. Tests

  13. Limitations

  14. License


Related MCP server: BossDrawer

Quick start

You need:

  • Claude Desktop (macOS or Windows) or Claude Code, or another app that supports MCP servers;

  • Python 3.12 or newer;

  • poppler, a small free tool for reading PDFs.

It is tested on Linux and should work the same on macOS. Windows is untested.

  1. Install poppler and pipx, then the tools:

    # macOS (with Homebrew):  brew install poppler pipx
    # Ubuntu / Debian:        sudo apt install poppler-utils pipx
    pipx install "git+https://github.com/delpapa/mcp-invoices-pt"
  2. Write your settings. Download config.example.yaml, save it as ~/.config/mcp-invoicesPT/config.yaml, and put your NIF in it. Every other setting has a sensible default:

    • documents arrive in ~/Downloads;

    • each tax year lives in ~/Taxes/<year>;

    • the books are an Excel file inside that folder.

  3. Create this year's books:

    mcp-invoices-pt init-sheet 2026

    This creates ~/Taxes/2026/ with Expenses/, Income/ and Bookkeeping_2026.xlsx.

  4. Connect it to your assistant.

  5. Download a few invoices and ask: "organize my receipts".


Who it is for

A trabalhador independente (freelancer issuing recibos verdes) who:

  • is in the normal VAT regime (not the art. 53.º exemption) and files the quarterly Declaração Periódica;

  • buys from Portuguese suppliers and from abroad (EU and non-EU software, cloud services, online shops);

  • sells to clients in Portugal, the EU or outside it;

  • uses e-Fatura and the Portal das Finanças (recibos verdes).

The usual cross-border cases are handled:

  • reverse charge (autoliquidação) on EU and non-EU services;

  • intra-EU purchases of goods;

  • foreign suppliers who charged you Portuguese or foreign VAT (OSS);

  • non-deductible IVA (meals, transport);

  • partial business use, e.g. 30% of home rent;

  • sales to clients in the EU (box 7) and outside it (box 8).

Supported documents

Portuguese documents, from any issuer (read from the official AT QR code):

  • Fatura (FT), fatura simplificada (FS), fatura-recibo (FR), nota de crédito (NC), nota de débito (ND), and recibo (RG/RC). That covers telecoms, utilities, landlords, shops and restaurants: anything issued by certified software.

  • PDFs, or a photo of the paper receipt.

  • The recibos verdes, faturas and faturas-recibo you issue on the Portal das Finanças.

  • The e-Fatura CSV export, for invoices that only exist there.

  • Your submitted Declaração Periódica PDF, used to check and lock a quarter you have filed.

Foreign layouts (one parser each):

Parser

Covers

Notes

stripe

Invoices and receipts hosted by Stripe, the layout many software and AI subscriptions are billed with

Supplier, country, VAT numbers (yours and theirs), totals, VAT charged, card ending

github

GitHub invoices and payment receipts

google_cloud

Google Cloud EMEA invoices

google_play

Google Play order receipts (the e-mail saved as PDF)

wise

Wise transfer confirmations

The expense is the fee, at Wise's own exchange rate

amazon

Amazon EU marketplace invoices issued by the seller (Spanish layout, Amazon.es)

Intra-EU goods: reverse charge

Your own sales invoices. If you also issue invoices of your own besides the Portal document, there is an example parser for a common template in examples/parsers/simple_invoice.py. Copy it into your private parsers folder and adapt it.

Anything else still works: the assistant reads the text itself. Once a layout is added as a parser, it no longer needs to.

How it reads documents

Each document goes through these layers in order, and the first one that works wins:

Layer

What

AI needed?

1. AT QR code

Every invoice from certified Portuguese software and every recibo verde has one (Portaria 195/2020). It holds the NIFs, date, number, ATCUD, and base and IVA per rate.

No

2. Layout parsers

One small module per invoice layout (list above).

No

3. e-Fatura export

The CSV from e-Fatura.

No

4. Plain text

Anything else: the assistant reads the text and fills the fields.

Yes

Every document is also checked for:

  • the card ending printed on a receipt;

  • reverse-charge wording (in English, Portuguese, German and Spanish);

  • "art. 138" intra-EU supplies;

  • Portuguese VAT charged by a foreign supplier.

From all that, the tools propose how to book the document:

  • the VAT code, which decides the IVA boxes;

  • the exchange rate: the official ECB rate for that day, or the rate printed on the document (e.g. Wise);

  • the payment account;

  • the business share;

  • the file name.

Your rules in the private config, per supplier and per client, override any of these.

Your folders and books

Folders

~/Taxes/2026/
├── Bookkeeping_2026.xlsx           the books
├── Expenses/                       every purchase document, renamed
│   ├── accountant_01_FT-A1-123.pdf
│   ├── github_02_INV000000001.pdf
│   └── ...
├── Income/                         your sales: your invoice (if any) and the Portal document
│   ├── 20260215_recibo_RG-A1-1.pdf
│   └── ...
├── eFatura_2026_export_20260415.csv
└── IVA_2026_1TRI_....pdf           your submitted returns (save them here)

File names are <supplier>_<month>_<document number>. The supplier part comes from your rules, the supplier's name, or its NIF.

The books

init-sheet YEAR (or asking the assistant to create the year's books) makes an Excel workbook, which opens in Excel, LibreOffice or Numbers. A Google Sheet is an option: set backend: google and see Google Sheets.

Expenses sheet

  • Declaração Periódica, one column per quarter:

    • the boxes you type on the Portal: 3, 4, 7, 8, 12, 13, 16, 17, 20, 24, 61 and 98;

    • the boxes the Portal calculates, so you can check them: 90, 91, 92, 93, 94 and 96.

    • Box 61 (the credit carried in) is the previous quarter's box 96. Q1's comes from the previous year's Q4.

  • QUARTERS: quarter sums under the table's columns.

  • The table, one row per purchase.

Income sheet

  • IRS & SS, per quarter:

    • gross income by invoice date, for IRS Anexo B;

    • income by recibo date, for the quarterly Segurança Social declaration;

    • business expenses.

  • The table, one row per sale.

The cells are ordinary formulas, so you can read, check and change the books by hand.

What the columns mean

Column

Meaning

Amount paid

What the document says you paid, in its own currency, VAT included

VAT included

The VAT inside that amount, in the same currency (0 when none was charged)

FX to EUR

Units of the foreign currency per 1 € (e.g. 1.10 for dollars), as the ECB publishes it; 1 for euros

Amount €, Net € (-VAT)

The same in euros, with and without VAT

NIF?

Whether the invoice shows your NIF. Portuguese IVA is only deductible if it does

VAT code

How the purchase is treated for IVA (table below); decides the boxes

Business %

Share used for work: 100% normally, e.g. 30% for home rent

Box N

That purchase's contribution to box N of the Declaração Periódica

Net VAT benefit €

IVA you get back minus IVA you self-charge (0 for reverse charge)

IRS deductible €

The business cost for IRS: what you paid, times the business share, minus the IVA you recover

Document

What backs the row: QR-verified PDF, invoice, receipt, e-Fatura only, no invoice, MISSING

Payment account

Which card or account paid

Q

The quarter, from the date

VAT codes (purchases)

Code

When

Boxes

PT

Portuguese IVA, deductible

24

PT-ASSET

Portuguese IVA on equipment you keep (e.g. a laptop)

20

PT-NONDED-MEAL

Meals: IVA not deductible (art. 21 CIVA)

–

PT-NONDED-TRAVEL

Transport of people: IVA not deductible

–

NoVAT

Exempt operation (e.g. rent)

–

NONE

Nothing to self-charge (bank and payment fees, no invoice)

–

EU-RC

Services from an EU supplier that charged no VAT (reverse charge)

16 + 17, deducted in 24

EU-RC-GOODS

Goods from an EU supplier that charged no VAT (reverse charge)

12 + 13, deducted in 24

NON-EU-RC

Services from outside the EU that charged no VAT (reverse charge)

3 + 4 and 98, deducted in 24

OSS-PT-VAT-NONDED

A foreign supplier charged you Portuguese IVA

not deductible

FOREIGN-VAT-NONDED

A foreign supplier charged another country's VAT

not deductible

Sales codes

Code

When

Boxes

PT / C3

Portuguese client, IVA at 23%

3 + 4

EU / C7

Business client in another EU country, no IVA

7, and the Declaração Recapitulativa

NON-EU / C8

Client outside the EU, no IVA

8

Box numbers follow the Declaração Periódica in force for periods before 1 July 2027. Portaria 298/2026 changes the return after that, and this project will follow.

Setup in detail

1. Install

With pipx (simplest; pipx installs a command-line program in its own space):

pipx install "git+https://github.com/delpapa/mcp-invoices-pt"            # add [google] for Google Sheets

From a clone (if you want to change the code):

git clone https://github.com/delpapa/mcp-invoices-pt && cd mcp-invoices-pt
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"                 # add ,google for Google Sheets

Either way you also need poppler: brew install poppler on macOS, or sudo apt install poppler-utils on Ubuntu / Debian.

2. Your private config

Save config.example.yaml as ~/.config/mcp-invoicesPT/config.yaml. Every line in it is commented. The settings that matter:

Setting

What to put

taxpayer.nif

Your NIF (required)

paths.inbox

Where downloads arrive. ~/Downloads works, but a dedicated folder is better: only what is in it gets looked at

paths.year_root

One folder per tax year, e.g. ~/Taxes/{year}

cards

The last 4 digits of your cards, in quotes, mapped to the account names you use: "1234": my-bank

suppliers

Optional per-supplier rules: a display name for Portuguese suppliers (their QR code carries only the NIF), a file-name prefix, the account, a VAT code, the business share

clients

Optional per-client rules for sales: name, tax id, country, VAT case, account

The config is YAML. Indentation matters, # starts a comment, and text values are safest in "quotes".

3. Create the year's books

mcp-invoices-pt init-sheet 2026                    # or: init-sheet 2026 <IVA credit carried in>

Without the credit, it is read from the previous year's Q4, if those books exist. You can also just ask the assistant to "create the 2026 books".

4. Connect to your assistant

Claude Code:

claude mcp add --scope user invoices-pt -- mcp-invoices-pt

Claude Desktop: open Settings → Developer → Edit Config (the file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, and %APPDATA%\Claude\claude_desktop_config.json on Windows), add this, and restart Claude Desktop:

{
  "mcpServers": {
    "invoices-pt": {"command": "/full/path/to/mcp-invoices-pt"}
  }
}

which mcp-invoices-pt in a terminal shows the full path; with pipx it is usually ~/.local/bin/mcp-invoices-pt. If your config is somewhere else, add "env": {"INVOICES_PT_CONFIG": "/path/to/config.yaml"} next to command.

5. Already have invoices filed?

Ask the assistant to "run index_year for 2026". Afterwards, a document you download again is recognised as a copy.

Optional: Google Sheets instead of Excel

  1. Install with [google] and set backend: google in the config.

  2. In a Google Cloud project, enable the Google Sheets API and create a service account.

  3. Download its JSON key to the path in google.service_account, and keep it private.

  4. Create a Google Sheet and share it with the service account's e-mail as Editor. Put the sheet's ID (from its URL) in google.spreadsheet_id.

  5. init-sheet YEAR then adds the year's tabs to that sheet.

Day-to-day use

Collect

  • Purchases:

    • download invoices and receipts from supplier portals (Stripe invoices, GitHub billing, cloud consoles, Amazon orders);

    • for paper receipts from Portuguese shops, photograph the QR code clearly.

  • Sales: the Portal document you issued (recibo verde, fatura or fatura-recibo). If you also send clients an invoice of your own, save that too.

  • Every so often: the e-Fatura export. On the Portal das Finanças: e-Fatura → Adquirente → Verificar faturas → export. It catches Portuguese invoices you never downloaded.

Ask

Close the workbook first if it is open in Excel or LibreOffice; the tools will not write to an open workbook.

You say

It does

"Organize my receipts."

Makes a plan of everything in the inbox and shows it to you. After you confirm, it files and books each document, books sales, checks the e-Fatura export, and reports what is missing. It asks about judgment calls, such as business or personal, or whether IVA is deductible

"What do I type for Q3?"

The Declaração Periódica boxes for the quarter, the credit carried over, and the result

"Q3 submitted."

Freezes that quarter's figures and locks its rows. If you saved the return PDF in the year folder, it compares the two; the submitted return is the source of truth

"What's missing for 2026?"

Rows marked MISSING, files that are gone, incomplete rows, unbooked files, receipts for payments already booked, gaps in monthly subscriptions, sales without a Portal document

"IRS and Segurança Social totals for 2026?"

Gross income, income by recibo date, business expenses, per quarter

"Create the 2027 books."

Next year's workbook, with the IVA credit carried over

Sales

  • The common case: only the Portal document. If you issue a fatura-recibo (or recibo verde) on the Portal and nothing else, that document is the sale. Its QR code gives the date, amount, IVA, withholding and client tax id. Add a clients rule so it books with the client's name.

  • With an invoice of your own: if you also send your own invoice (e.g. in dollars to a foreign client), the plan pairs it with its Portal document by date and amount. The row keeps both, and the exchange rate implied by the two.

Type the return

On the Portal das Finanças, under IVA → Declaração Periódica, fill quadro 06 and 06-A with the boxes from "What do I type for Q3?". Box 61 is the credit carried in. After submitting, save the PDF in the year folder and say "Q3 submitted".

Fixing a mistake

Edit the workbook directly: the tools read whatever is there, and the formulas recalculate. The exception is a quarter you marked as submitted: its declaration figures are frozen, so later edits to its rows no longer change them. To deliberately correct a filed quarter, ask the assistant. That is also when you would file a substitute return.

A new year

Ask for the new year's books, or run init-sheet <year>. The IVA credit carries over automatically.

Tools reference

Tool

Arguments

Does

plan_inbox

–

Reads everything in the inbox and returns the plan, writing nothing: expense rows, sales (paired), documents to read, copies, non-invoices, e-Fatura exports

scan_inbox

–

Lists the files in the inbox with their kind, whether they read like an invoice, and their status (new, read, filed)

extract

path, read_anyway

Reads one document and proposes how to book it. Text that does not read like an invoice is withheld unless read_anyway

file_document

path, name, dry_run

Moves a document into its year folder (expenses or income) under the proposed name. If it is a copy of a filed document, deletes the download instead

add_expense

row, dry_run

Adds a purchase; refuses duplicates and filed quarters

propose_income

invoice_path, at_document_path

Proposes one sale from your invoice and/or the Portal document

add_income

row, dry_run

Adds a sale

read_efatura / reconcile_efatura

csv_path (, year)

Reads an e-Fatura export / compares it with the books

missing

year

What is still missing, expenses and income

vat_return

quarter, year

The Declaração Periódica boxes for a quarter

mark_filed

quarter, year, return_pdf, dry_run, apply_pdf_values

Freezes and locks a submitted quarter, checked against the return PDF

income_totals

year

IRS and Segurança Social totals

create_year_sheet

year, opening_credit, dry_run

Creates a year's books and folders

index_year

year

Records the documents already filed, so copies are recognised

vat_codes

–

The VAT codes and the boxes each fills

Safety

  • Dry run first. Every tool that changes something shows what it would do first, and only acts when told to.

  • Files.

    • Documents are never overwritten.

    • Only files in the inbox are ever deleted, and only when they are copies of documents already filed.

    • Files that do not look like invoices are flagged and not read, unless you ask.

  • Books.

    • No duplicate rows.

    • Rows are kept sorted by date. The table is rewritten when sorting, so colours or fonts you add to its cells by hand may be reset.

    • A filed quarter's figures are frozen, and the tools refuse to add rows to it.

  • The workbook. Writes are atomic, so an interruption never leaves half a file. Nothing is written while the workbook is open elsewhere.

  • Numbers. The tools compute the boxes in Python, mirroring the workbook's formulas with spreadsheet rounding. The test suite recalculates a workbook in LibreOffice and checks both agree to the cent.

  • Internet is only used for ECB exchange rates. Without it, foreign-currency documents ask you for the rate.

Privacy: public code, private data

Everything personal stays outside this repository, under ~/.config/mcp-invoicesPT/:

In the repository

In your private folder

Document readers, Portuguese VAT rules, the layout of the books, the tools

config.yaml: NIF, folders, cards → accounts, supplier and client rules

Tests with made-up documents only

parsers/: your own parsers (e.g. your personal invoice template)

An example parser to adapt

The Google service-account key (Google backend only)

The ledger of files already handled (~/.local/share/mcp-invoicesPT/)

What the AI sees. Documents are read on your computer. The assistant receives what the tools return:

  • each document's fields;

  • the text of documents in unknown layouts;

  • never the text of files that do not look like invoices, unless you ask.

Your assistant's privacy terms apply to what it receives.

Adding a document type

A parser is a Python module with three things:

NAME = "acme"

def matches(text: str) -> bool:                    # is this document in my layout?
    return "ACME Cloud Ltd" in text and "Invoice number" in text

def parse(text: str, file: str = "") -> Document:  # read its fields
    ...

parse returns a Document with these fields: layer, doc_type, date, supplier, supplier_vat, country, invoice_no, currency, amount, vat_included, buyer_nif, markers and extra. Helpers for amounts in both number formats, dates in several languages, and country names are in documents/parsers/_common.py.

  • A company's layout that others may use: add it to src/invoices_pt/documents/parsers/, with a made-up sample in tests/test_parsers.py (never real data), and open a pull request. The registry picks it up automatically.

  • Something only you use (e.g. your own invoice template): put it in a private folder and set parsers_dir in the config. It is loaded at start-up and tried before the public parsers.

Tests

.venv/bin/pytest -q

The suite uses made-up documents only. It covers:

  • every parser, QR codes and the e-Fatura import;

  • VAT coding, filing and the inbox plan;

  • the missing-documents report and sales;

  • a complete workbook, with every box checked against hand-computed values (and recalculated in LibreOffice, if it is installed).

Opt-in checks against your own data:

INVOICES_PT_LIVE_SHEET=1 .venv/bin/pytest tests/test_live_layout.py -q
INVOICES_PT_PRIVATE=1 INVOICES_PT_YEAR=2026 .venv/bin/pytest tests/test_private_regression.py -q -s
  • test_live_layout.py (Google backend) builds temporary tabs in your sheet, checks every box, and removes them.

  • test_private_regression.py re-reads your filed documents and compares them with your booked rows.

Limitations

  • Quarterly filers only. The IVA you self-charge on reverse charge is at the mainland rate (23%). Monthly filing and the Azores and Madeira rates are not handled yet.

  • IRS: the figures assume the regime simplificado (Anexo B). Organised accounting is out of scope.

  • The return model: box numbers follow the Declaração Periódica valid until June 2027.

  • Photos: reading a paper receipt depends on how sharp its QR code is in the photo.

  • Windows is untested.

License

This is a tool I have been writing for myself first. I keep the generic part here, separate from any personal settings, so others can use it too.

MIT. You can use, change and share this freely, including commercially, as long as you keep the copyright notice. It comes as is, with no warranty of any kind: I do not guarantee that it is correct or fit for your situation, and it is not tax advice. Issues and pull requests are welcome.

Available Tools

16 tools
add_expenseA

Add one expense row to the year's expenses tab. row keys: date (YYYY-MM-DD), expense, supplier, country, supplier_vat, invoice_no, currency, amount, vat_included, fx, nif, code, business_pct, document, file, account. Refuses duplicates and quarters already filed. Call with dry_run=true first.

Inputs: row (required), dry_run.

add_incomeA

Add one sale to the year's income tab. row keys: invoice_date (YYYY-MM-DD), client, country, client_tax_id, invoice_no, recibo_no, recibo_date, currency, amount, fx, net_eur, vat_rate, vat_eur, withheld, vat_case, invoice_file, recibo_file, account. Refuses duplicates and filed quarters. Dry run first.

Inputs: row (required), dry_run.

create_year_sheetB

Create a tax year's books: a local .xlsx workbook (default) or tabs in a Google Sheet, per the config. Expenses and income tables with the Declaração Periódica block (what to type each quarter, with the credit carried over), quarter sums, IRS / Segurança Social totals, formulas, dropdowns and formats. The opening credit (Q1 box 61) defaults to the previous year's Q4 box 96. Refuses to overwrite.

Inputs: year (required), dry_run, opening_credit.

extractA

Read one invoice or receipt (PDF or photo). Returns the document fields, which layer read them (qr / parser: / text), a booking proposal (VAT code, region, ECB rate, payment account, business share, document label, file name) and a ready expense row. If a PDF does not read like an invoice or receipt, its text is withheld unless read_anyway=true, so unrelated documents are not exposed.

Inputs: path (required), read_anyway.

file_documentA

Move a document from the inbox into its tax-year folder under the proposed name (or name). If the same file or the same invoice is already filed, the inbox copy is deleted instead. Never overwrites and never deletes outside the inbox. e-Fatura CSV exports go to the year folder. Dry run first.

Inputs: path (required), name, dry_run.

income_totalsB

The IRS and Segurança Social totals at the top of the income tab, per quarter and for the year: gross income by invoice date (IRS), income by recibo date (Segurança Social quarterly declaration), and business expenses.

Inputs: year (required). Returns: result

index_yearA

Read every document already in the year's folders into the ledger, so later copies are recognised. Run it once per year (and again after moving files by hand).

Inputs: year (required).

mark_filedA

After the user submits a quarter: freeze its declaration values, grey them and lock (warning-only) the quarter's block column, expense rows and income rows. If the submitted return PDF is in the year folder (or given), its boxes are compared with the sheet; apply_pdf_values=true copies the PDF's values over the frozen ones, since the submitted return is the source of truth. Dry run first.

Inputs: year (required), quarter (required), dry_run, return_pdf, +1 more.

missingA

What is still missing for a year: rows flagged MISSING, rows whose file is not in the folder, rows without a date, amount or invoice number, files in the folder no row books (and receipts that duplicate a booked payment), and months missing in monthly subscriptions. For income: sales without an AT document yet, missing files and unbooked files.

Inputs: year (required).

plan_inboxA

Read everything in the inbox and return the plan, without writing anything: expense rows ready for add_expense (with the file name for file_document and any checks to resolve), sales ready for add_income (your invoice paired with its AT document), documents to read yourself, copies, non-invoices, e-Fatura exports.

Inputs: no named parameters.

propose_incomeB

Read one sale: your own invoice and/or the AT document issued on the Portal (recibo verde, fatura or fatura-recibo). Returns the income row (client, tax id, recibo no. and date, amount, rate, IVA, withholding, VAT case), the file names to file both under, and checks that the two documents belong together.

Inputs: invoice_path, at_document_path.

read_efaturaB

Parse an e-Fatura CSV export into documents, each with a booking proposal.

Inputs: csv_path (required). Returns: result

reconcile_efaturaB

Compare an e-Fatura CSV export with the expenses tab: invoices not in the sheet, rows whose amount, VAT or invoice number differ (or that lack fields e-Fatura has), and Portuguese rows e-Fatura lacks.

Inputs: year (required), csv_path (required).

scan_inboxA

List the files in the inbox folder (PDFs, images, e-Fatura CSVs), newest first: kind (document, not_an_invoice, efatura_export), whether a PDF reads like an invoice, its status in the ledger (new, extracted, filed) and whether it is an exact copy of another inbox file.

Inputs: no named parameters. Returns: result

vat_codesB

The purchase and sales VAT codes the sheet understands, and which return boxes each one fills.

Inputs: no named parameters.

vat_returnB

The Declaração Periódica boxes for a quarter (Q1-Q4) as the sheet shows them, including the credit carried over (box 61) and the result boxes 90-96, and whether the quarter is already filed.

Inputs: year (required), quarter (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    The tools mostly map to distinct workflow stages: inbox scanning/planning, document extraction, expense/income booking, filing, reconciliation, VAT reporting, and year-sheet lifecycle. There is some potential overlap around e-Fatura reading versus reconciliation and inbox planning versus scanning, but the descriptions make the intended boundaries fairly clear.

    Naming Consistency4/5

    All names use snake_case, and most follow a verb_noun pattern such as add_expense, file_document, reconcile_efatura, and create_year_sheet. A few departures like extract, missing, income_totals, vat_return, and vat_codes are still readable but slightly less predictable.

    Tool Count4/5

    Sixteen tools is slightly above the typical well-scoped range, but it is reasonable for a domain involving inbox processing, expenses, income, e-Fatura reconciliation, VAT returns, and tax-year sheet lifecycle. Each tool appears to cover a meaningful step rather than duplicating another.

    Completeness4/5

    The surface covers the main lifecycle: extracting documents, planning inbox work, adding expenses and income, filing documents, reconciling e-Fatura, checking missing items, generating VAT returns, creating year sheets, and marking quarters filed. Minor gaps remain around querying or updating/deleting individual booked rows, but core workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides complete Portuguese invoice management with 60+ specialized tools including invoice creation, client management, SAF-T tax compliance, treasury operations, and Portuguese Tax Authority (AT) integration for AI-powered business automation.
      9 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Helps small business owners classify business documents and messages, extract key information like dates and amounts, generate action checklists, check missing documents, and draft business messages for accountants, clients, and employees.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to inspect and extract invoice metadata from PDFs, Word documents, Excel files, and images, then synchronize and enrich the extracted data into an Excel ledger.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to convert, build, validate, and transfer bookkeeping journals between Spanish accounting formats and spreadsheet CSV, including turning Norma 43 bank statements into journal entries.
      11
      450 PyPI
      Business Source 1.1