Aruba Fatturazione Elettronica MCP Read-only

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

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.