SAF-T MCP Server

Parse and analyze Portuguese SAF-T tax files with AI assistants

Getting Started · Available Tools · Configuration

Versao em Portugues · 13 tools · 152 tests

A Model Context Protocol (MCP) server that enables AI assistants like Claude, Cursor, and Windsurf to load, validate, and analyze Portuguese SAF-T (Standard Audit File for Tax Purposes) XML files. Load a SAF-T file and immediately query invoices, get revenue summaries, VAT breakdowns, and validate compliance with Portuguese tax rules.

What is SAF-T PT?

SAF-T PT is a mandatory XML file that all Portuguese companies must be able to export from their accounting/billing software. It contains the company's invoices, payments, customers, products, tax entries, and more. This MCP server turns that XML into a queryable data source for AI assistants.

Quick Start

Prerequisites

• Python 3.11+ and uv (recommended) or pip

• A SAF-T PT XML file exported from any Portuguese billing/accounting software (PHC, Sage, Primavera, etc.)

1. Install

pip install saft-mcp

Or from source:

git clone https://github.com/bybloom-ai/saft-mcp.git
cd saft-mcp
uv sync

2. Add to your AI assistant

claude mcp add saft-mcp -- /path/to/saft-mcp/.venv/bin/python -m saft_mcp

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "saft-mcp": {
      "command": "/path/to/saft-mcp/.venv/bin/python",
      "args": ["-m", "saft_mcp"]
    }
  }
}

Add to your MCP client configuration:

{
  "mcpServers": {
    "saft-mcp": {
      "command": "/path/to/saft-mcp/.venv/bin/python",
      "args": ["-m", "saft_mcp"]
    }
  }
}

3. Start using it

Ask your AI assistant:

"Load my SAF-T file at ~/Documents/saft_2025.xml and give me a revenue summary"

The server will parse the file, extract all invoices and tax data, and make it available for querying through natural conversation.

Related MCP server: mcp-csv-analyst

Available Tools

saft_load

Load and parse a SAF-T PT XML file. This must be called first before using any other tool.

Returns company name, NIF, fiscal period, SAF-T version, and record counts (customers, products, invoices, payments).

Handles Windows-1252 and UTF-8 encodings, BOM stripping, and automatic namespace detection. Files under 50 MB are parsed with full DOM; larger files use streaming.

saft_validate

Validate the loaded file against the official XSD schema and Portuguese business rules.

Available rules:

Returns results with severity (error/warning), location, and fix suggestions.

saft_summary

Generate an executive summary of the loaded file. No parameters needed.

Returns:

• Revenue totals (gross, credit notes, net)

• Invoice and credit note counts

• VAT breakdown by rate

• Top 10 customers by revenue

• Document type distribution (FT, FR, NC, ND, FS)

saft_query_invoices

Search and filter invoices with full pagination.

Returns matching invoices with document number, date, type, customer, amounts, status, and line count.

saft_tax_summary

Generate a VAT analysis grouped by rate, month, or document type.

Returns taxable base, VAT amount, and gross total per group, plus overall totals.

saft_query_customers

Search and filter customer master data with revenue enrichment.

Returns customers with invoice count and total revenue per customer.

saft_query_products

Search and filter the product catalog with sales statistics.

Returns products with times sold, total quantity, and total revenue.

saft_get_invoice

Get full detail for a single invoice including all line items.

Returns complete invoice with header, document totals, special regimes, and all lines with product, quantity, price, tax, exemptions, and references.

saft_anomaly_detect

Detect suspicious patterns and irregularities in the loaded file.

Available checks:

Returns anomalies with type, severity, description, and affected documents.

saft_compare

Compare the loaded SAF-T file against a second file (e.g. month-over-month, year-over-year).

Available metrics: revenue, customers, products, doc_types, vat.

Returns period labels and a changes dict with before/after/delta per metric. Includes top new/lost customers, top movers, and percentage changes.

saft_aging

Compute accounts receivable aging from invoices and payments.

Returns per-customer aging with amounts in each bucket, sorted by total outstanding. Uses FIFO allocation of payments against invoices.

saft_export

Export data to CSV files for use in spreadsheets or other tools.

Returns file path, row count, and column names.

saft_stats

Generate a statistical overview of invoicing data.

Returns invoice statistics (mean, median, std deviation), daily/weekly/monthly distributions, customer concentration (Pareto analysis), and top/bottom invoices.

Typical Workflow

1. saft_load            -> Parse the XML file
2. saft_validate        -> Check compliance (XSD + business rules)
3. saft_summary         -> Get the big picture (revenue, top customers, VAT)
4. saft_query_invoices  -> Drill into specific invoices
5. saft_get_invoice     -> Full detail for a single invoice
6. saft_tax_summary     -> VAT analysis by rate, month, or doc type
7. saft_anomaly_detect  -> Flag suspicious patterns
8. saft_stats           -> Statistical distributions and trends
9. saft_compare         -> Diff against another SAF-T file
10. saft_export         -> Export results to CSV

Example questions you can ask after loading a file:

• "How much revenue did the company make this year?"

• "Show me all credit notes above 500 euros"

• "What's the monthly VAT breakdown?"

• "Are there any validation errors in this file?"

• "List invoices for customer XPTO in Q3"

• "What percentage of revenue comes from the top 5 customers?"

• "Are there any suspicious patterns or anomalies?"

• "Compare this file against last month's SAF-T"

• "What's the accounts receivable aging?"

• "Export all invoices to CSV"

Configuration

All settings are configurable via environment variables with the SAFT_MCP_ prefix:

Architecture

AI Assistant (Claude, Cursor, etc.)
        |
        | MCP Protocol (stdio)
        v
+------------------------------------------+
|           saft-mcp server                |
|                                          |
|  server.py       FastMCP entry point     |
|  state.py        Session management      |
|                                          |
|  parser/                                 |
|    detector.py   Namespace detection     |
|    encoding.py   Charset handling        |
|    full_parser.py   DOM parse (< 50 MB)  |
|    models.py     Pydantic data models    |
|                                          |
|  tools/                                  |
|    load.py            saft_load          |
|    validate.py        saft_validate      |
|    summary.py         saft_summary       |
|    query_invoices.py  saft_query_invoices|
|    query_customers.py saft_query_customer|
|    query_products.py  saft_query_products|
|    get_invoice.py     saft_get_invoice   |
|    tax_summary.py     saft_tax_summary   |
|    anomaly_detect.py  saft_anomaly_detect|
|    compare.py         saft_compare       |
|    aging.py           saft_aging         |
|    export.py          saft_export        |
|    stats.py           saft_stats         |
|                                          |
|  validators/                             |
|    xsd_validator.py   XSD 1.04_01        |
|    business_rules.py  Numbering, totals  |
|    nif.py             NIF mod-11         |
|    hash_chain.py      Hash continuity    |
|                                          |
|  schemas/                                |
|    saftpt1.04_01.xsd  Official XSD       |
+------------------------------------------+

Key design decisions:

• All monetary values use Decimal to avoid floating-point rounding in tax calculations

• lxml for XML parsing, with automatic XSD 1.1 feature stripping (the official Portuguese XSD uses xs:assert and xs:all with unbounded children, which lxml's XSD 1.0 engine cannot handle natively)

• Pydantic v2 models validated against real PHC Corporate exports

• Namespace auto-detection by scanning the first 4 KB of the file (never hardcoded)

• Windows-1252 encoding handled natively via the XML declaration

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests (152 tests)
pytest

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Type check
mypy src/

Project structure

saft-mcp/
  src/saft_mcp/         # Source code
    server.py           # FastMCP entry point, tool registration
    config.py           # Settings (pydantic-settings, env vars)
    state.py            # Session store, parsed file state
    exceptions.py       # SaftError hierarchy
    parser/             # XML parsing (encoding, detection, models)
    tools/              # One file per MCP tool
    validators/         # XSD, business rules, NIF, hash chain
    schemas/            # Official XSD file
  tests/                # Mirrors src/ structure
  pyproject.toml        # Project config (hatch build, ruff, mypy, pytest)

Roadmap

• saft_query_customers -- search and filter customer master data

• saft_query_products -- search and filter product catalog

• saft_get_invoice -- full invoice detail with line items

• saft_anomaly_detect -- flag duplicate invoices, numbering gaps, unusual amounts

• saft_compare -- diff two SAF-T files (e.g. month-over-month)

• saft_aging -- accounts receivable aging analysis

• saft_export -- export data to CSV

• saft_stats -- statistical overview and distributions

• Streaming parser for large files (>= 50 MB)

• Accounting SAF-T support (journal entries, general ledger, trial balance)

• saft_trial_balance -- generate trial balance from accounting data

• saft_ies_prepare -- pre-fill IES annual tax return fields

• saft_cross_check -- cross-reference invoicing vs accounting SAF-T

• PyPI package (pip install saft-mcp)

• GitHub Actions CI (pytest + ruff + mypy)

Supported SAF-T versions

• SAF-T PT 1.04_01 (current Portuguese standard)

Tested with real exports from PHC Corporate. Should work with SAF-T files from any compliant Portuguese software (Sage, Primavera, PHC, Moloni, InvoiceXpress, etc.).

License

MIT

Built by bybloom.ai, a business unit of Bloomidea