Aruba Fatturazione Elettronica

PyPI version Python versions License CI Container Ruff mypy Coverage GitHub release Downloads

Documentation: https://mnbro.github.io/aruba-fatturazione-elettronica-mcp/

• Tool list: https://mnbro.github.io/aruba-fatturazione-elettronica-mcp/tools/
• Docker: https://mnbro.github.io/aruba-fatturazione-elettronica-mcp/docker/
• LLM-friendly tools: https://mnbro.github.io/aruba-fatturazione-elettronica-mcp/llm-tools/
• API parity: https://mnbro.github.io/aruba-fatturazione-elettronica-mcp/api-parity/

This MCP server exposes read-only Aruba Fatturazione Elettronica API operations. It does not send invoices, upload files, accept or reject invoices, update resources, delete resources, or expose business POST/PUT/PATCH/DELETE operations.

Authentication uses POST /auth/signin because Aruba requires it for signin and refresh token lifecycle. Those POST requests are internal auth operations only.

The server also includes LLM-friendly read-only tools for fiscal document normalization, document context, lifecycle status, risk checks, FatturaPA XML parsing, SDI notification explanations, VAT summaries, duplicate/anomaly checks, safe redaction and generic Markdown/event exports. The optional local SQLite index writes only to the configured local database path and never modifies Aruba.

This is an Aruba Fatturazione Elettronica domain MCP, not a business workflow orchestrator. It does not call other MCP servers or integrate with external CRM, email, wiki, chat, billing or reporting systems.

Badges for PyPI, release, downloads and Codecov become active after the first publication/release and Codecov setup.

License

This project is licensed under the PolyForm Internal Use License 1.0.0.

You may use and modify it for your own internal business operations, including commercial internal use. You may not redistribute it, resell it, sublicense it, or offer it as a productized service to third parties.

Install

uv sync
cp .env.example .env

Set ARUBA_ENV=demo first unless you have a specific reason to start in production.

Run

uv run aruba-fatturazione-elettronica-mcp

python -m aruba_fatturazione_elettronica_mcp is also supported.

Docker

The Debian slim based container image is published to GitHub Container Registry:

docker run --rm -i \
  --env ARUBA_ENV=demo \
  --env ARUBA_USERNAME \
  --env ARUBA_PASSWORD \
  ghcr.io/mnbro/aruba-fatturazione-elettronica-mcp:latest

See the Docker documentation for MCP client configuration and local index volume setup.

LLM-friendly helpers

Recommended helper tools for agents:

• normalize_fiscal_document
• get_document_context
• fiscal_document_summary
• document_lifecycle_status
• document_risk_check
• validate_fiscal_document_consistency
• counterparty_document_history
• list_pending_or_problem_documents
• fiscal_period_summary
• tax_summary
• export_fiscal_events
• export_document_markdown
• export_period_markdown
• export_counterparty_markdown
• prepare_document_match_hints

These helpers are built over the existing read-only Aruba wrappers. They normalize, summarize, validate and export fiscal document context without modifying Aruba state.

MCP client config

{
  "mcpServers": {
    "aruba-fatturazione-elettronica-readonly": {
      "command": "uvx",
      "args": ["aruba-fatturazione-elettronica-mcp"],
      "env": {
        "ARUBA_ENV": "demo",
        "ARUBA_USERNAME": "...",
        "ARUBA_PASSWORD": "..."
      }
    }
  }
}

API parity table

Aruba section	Aruba endpoint	MCP tool	Implemented	Sensitive read	Binary
Auth	GET /auth/userInfo	aruba_get_user_info	yes	no	no
Auth	GET /auth/multicedenti	aruba_list_multicedenti	yes	no	no
Auth	GET /auth/multicedenti/{id}	aruba_get_multicedente_by_id	yes	no	no
Sent invoices	GET /services/invoice/out/findByUsername	aruba_find_sent_invoices	yes	no	no
Sent invoices	GET /services/invoice/out/getByFilename	aruba_get_sent_invoice_by_filename	yes	conditional	no
Sent invoices	GET /services/invoice/out/getZipByFilename	aruba_get_sent_invoice_zip_by_filename	yes	yes	yes
Sent invoices	GET /services/invoice/out/{invoiceId}	aruba_get_sent_invoice_by_id	yes	conditional	no
Sent invoices	GET /services/invoice/out/getByIdSdi	aruba_get_sent_invoice_by_sdi_id	yes	conditional	no
Sent invoices	GET /services/invoice/out/pdd	aruba_get_sent_invoice_pdd	yes	yes	yes
Received invoices	GET /services/invoice/in/findByUsername	aruba_find_received_invoices	yes	no	no
Received invoices	GET /services/invoice/in/getByFilename	aruba_get_received_invoice_by_filename	yes	conditional	no
Received invoices	GET /services/invoice/in/getZipByFilename	aruba_get_received_invoice_zip_by_filename	yes	yes	yes
Received invoices	GET /services/invoice/in/{invoiceId}	aruba_get_received_invoice_by_id	yes	conditional	no
Received invoices	GET /services/invoice/in/getByIdSdi	aruba_get_received_invoice_by_sdi_id	yes	conditional	no
Received invoices	GET /services/invoice/in/getInvoiceWithUnsignedFile	aruba_get_received_invoice_unsigned_file	yes	yes	no
Received invoices	GET /services/invoice/in/pdd	aruba_get_received_invoice_pdd	yes	yes	yes
Sent notifications	GET /services/notification/out/getByFilename	aruba_get_sent_notification_by_filename	yes	yes	no
Sent notifications	GET /services/notification/out/getByInvoiceFilename	aruba_get_sent_notifications_by_invoice_filename	yes	yes	no
Sent notifications	GET /services/notification/out/{invoiceId}	aruba_get_sent_notifications_by_invoice_id	yes	yes	no
Received notifications	GET /services/notification/in/getByFilename	aruba_get_received_notification_by_filename	yes	yes	no
Received notifications	GET /services/notification/in/getByInvoiceFilename	aruba_get_received_notifications_by_invoice_filename	yes	yes	no
Received notifications	GET /services/notification/in/{invoiceId}	aruba_get_received_notifications_by_invoice_id	yes	yes	no
Customer result	GET /services/invoice/in/sendEsitoCommittente/{filename}	aruba_get_customer_result_status	yes	no	no

Security notes

Some responses can contain fiscal XML, PDF, ZIP or Base64 payloads with sensitive tax data. Credentials are read only from environment variables. Tokens, passwords, Base64, XML, PDF, ZIP and likely VAT/fiscal codes are redacted from logs.

Use dedicated credentials where possible, not shared admin accounts. Verify contractually that Aruba Web Services/API access is enabled for your account. Start with ARUBA_ENV=demo.

Attribution

Inspired by these projects:

• zangetsu02/fatturazione-elettronica-aruba
• andreafalzetti/node-fatturazione-elettronica-aruba

No code was copied verbatim in this implementation. Preserve original notices if future changes adapt source code from third-party projects.