mcp-server-acube

A Model Context Protocol (MCP) server that provides 38 tools for interacting with the A-Cube API -- the Italian electronic invoicing platform for SDI (Sistema di Interscambio), FatturaPA, smart receipts, company verification, and more.

Connect this server to Claude Desktop, Claude Code, or any MCP-compatible client to manage Italian electronic invoicing through natural language.

Features

• Electronic Invoicing -- Send, list, and retrieve FatturaPA invoices via SDI, with support for JSON, XML, PDF, and HTML formats
• AI-Powered PDF Extraction -- Convert PDF invoices to FatturaPA format using A-Cube's AI extraction pipeline
• Smart Receipts -- Issue, void, and manage electronic receipts (scontrini elettronici)
• Company Verification -- Look up Italian companies by P.IVA or codice fiscale, verify fiscal IDs, and check split payment status
• SDI Notifications -- Monitor delivery receipts, rejections, and all other SDI notification types
• Cassetto Fiscale -- Schedule recurring or one-time bulk downloads from the Agenzia delle Entrate tax drawer
• Webhooks -- Configure real-time event callbacks for 13 different event types
• Business Registry & ADE Appointees -- Manage company profiles and fiscal intermediary configurations
• Token-Optimized Responses -- Compact JSON output with null stripping and field selection to minimize LLM token consumption
• Automatic Authentication -- JWT token management with automatic refresh (24h token lifetime)
• Sandbox & Production -- Seamlessly switch between A-Cube sandbox and production environments

Quick Start

Prerequisites

You need an A-Cube API account. Sign up at acubeapi.com to get your credentials.

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "acube": {
      "command": "npx",
      "args": ["-y", "mcp-server-acube"],
      "env": {
        "ACUBE_EMAIL": "[email protected]",
        "ACUBE_PASSWORD": "your-password",
        "ACUBE_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Claude Code

claude mcp add acube -- npx -y mcp-server-acube \
  -e [email protected] \
  -e ACUBE_PASSWORD=your-password \
  -e ACUBE_ENVIRONMENT=sandbox

Or add it manually to .mcp.json in your project root:

{
  "mcpServers": {
    "acube": {
      "command": "npx",
      "args": ["-y", "mcp-server-acube"],
      "env": {
        "ACUBE_EMAIL": "[email protected]",
        "ACUBE_PASSWORD": "your-password",
        "ACUBE_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Configuration

The server is configured through environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | ACUBE_EMAIL | Yes | -- | Your A-Cube account email | | ACUBE_PASSWORD | Yes | -- | Your A-Cube account password | | ACUBE_ENVIRONMENT | No | sandbox | API environment: sandbox or production |

Available Tools

Invoices (4 tools)

| Tool | Description | |---|---| | send_invoice | Send a FatturaPA electronic invoice to SDI. Accepts the complete FatturaPA JSON object. Returns the UUID assigned by SDI (HTTP 202). Supports optional digital signing. | | send_simplified_invoice | Send a simplified FatturaPA invoice (fattura semplificata) for amounts up to 400 EUR. | | list_invoices | List and filter invoices with 20+ filters (sender/recipient name, VAT, status, date ranges, invoice series, etc.). Returns a compact default view -- see Response Optimization. | | get_invoice | Retrieve a specific invoice by UUID. Output formats: JSON, XML (FatturaPA), PDF (base64), or HTML. Supports field selection. |

Invoice Extraction (3 tools)

| Tool | Description | |---|---| | extract_invoice_from_pdf | Upload a PDF invoice (base64-encoded) for AI-powered conversion to FatturaPA format. Returns a job UUID. | | get_extraction_status | Poll the status of a PDF extraction job by UUID. | | get_extraction_result | Retrieve the converted FatturaPA invoice from a completed extraction job. Available in JSON or XML format. |

Notifications (3 tools)

| Tool | Description | |---|---| | list_notifications | List SDI notifications with filtering by type (NS, MT, RC, MC, EC, SE, NE, DT, AT) and download status. | | get_notification | Get a specific SDI notification by UUID in JSON or original XML format. | | mark_notifications_downloaded | Mark one or more notifications as downloaded by providing their UUIDs. |

Verification (4 tools)

| Tool | Description | |---|---| | verify_fiscal_id | Validate an Italian codice fiscale or P.IVA against the Agenzia delle Entrate. | | verify_company | Full company lookup by P.IVA or codice fiscale. Returns name, PEC, SDI code, address, ATECO code, shareholders, and more. | | verify_simple_company | Basic company info lookup -- a lightweight alternative to verify_company. | | verify_split_payment | Check if a company has split payment (scissione dei pagamenti) status for public administration invoicing. |

Smart Receipts (4 tools)

| Tool | Description | |---|---| | send_receipt | Issue an electronic receipt (scontrino elettronico) with items, payment amounts, and fiscal ID. | | get_receipt_details | Get receipt transaction details including document number. | | void_receipt | Void/cancel an electronic receipt (annullamento). | | return_receipt_items | Process item returns against an existing receipt. |

Webhooks (5 tools)

| Tool | Description | |---|---| | list_webhook_configs | List all webhook configurations. | | create_webhook_config | Subscribe to events by specifying an event type and target URL. Supports 13 event types including supplier-invoice, customer-invoice, receipt, and more. | | get_webhook_config | Get a specific webhook configuration by ID. | | update_webhook_config | Update webhook settings (event type, URL, authentication). | | delete_webhook_config | Remove a webhook configuration. |

Business Registry & ADE Appointees (8 tools)

| Tool | Description | |---|---| | list_business_registries | List all business registry configurations (anagrafiche aziendali). | | create_business_registry | Create a new company profile for electronic invoicing, including fiscal ID, signature, and legal storage settings. | | get_business_registry | Get a specific business registry configuration by ID. | | update_business_registry | Update an existing company profile. | | list_appointees | List all ADE tax appointees (intermediari fiscali). | | create_appointee | Register a new fiscal intermediary authorized to operate with the Agenzia delle Entrate. | | get_appointee | Get a specific ADE appointee by ID. | | update_appointee | Update an existing fiscal intermediary. |

Cassetto Fiscale & Rejected Invoices (7 tools)

| Tool | Description | |---|---| | schedule_invoice_download | Set up recurring daily invoice downloads from the Cassetto Fiscale (tax drawer) at 03:00 UTC. | | get_download_schedule | Check the status of an invoice download schedule (active, auto-renewal, last execution). | | update_download_schedule | Modify download schedule options. | | delete_download_schedule | Stop recurring invoice downloads. | | download_invoices_once | Trigger a one-time bulk invoice download by date range from the Agenzia delle Entrate. | | count_rejected_invoices | Count invoices that were rejected during Cassetto Fiscale processing. | | recover_rejected_invoices | Reprocess previously rejected invoices for a given fiscal ID and date range. |

Response Optimization

This server is designed to minimize LLM token consumption. Every response goes through three optimizations:

1. Payload parsing

The A-Cube API returns the FatturaPA invoice data as a raw JSON string in the payload field. The server automatically parses this string into a structured object, which enables null stripping to work on the ~60 null fields inside it. This eliminates double-encoding overhead (\" escapes) and typically cuts payload token usage by ~50%.

2. Null stripping

All null and undefined values are recursively removed from responses -- including inside the parsed payload. A typical invoice sender object has ~40 fields, of which ~30 are null. After stripping, only the 5--8 populated fields remain.

3. Compact JSON

Responses are serialized without indentation (JSON.stringify(data) instead of JSON.stringify(data, null, 2)). This eliminates whitespace tokens that provide no information to the LLM.

4. Default field selection on list_invoices

The list_invoices tool returns a compact default view (10 items per page) instead of the full A-Cube response. The raw API response includes the entire FatturaPA payload (~2000 tokens per invoice) and full sender/recipient objects. The compact view extracts only the essential fields:

| Default field | Description | |---|---| | uuid | Invoice UUID | | created_at | Creation timestamp on A-Cube | | document_type | FatturaPA type code (TD01, TD04, etc.) | | marking | SDI status (delivered, rejected, sent, etc.) | | notice | Error message from SDI (if rejected) | | invoice_number | Invoice number (extracted from payload) | | invoice_date | Invoice date (extracted from payload) | | total_amount | Total document amount (extracted from payload) | | currency | Currency code (extracted from payload) | | sender.business_name | Sender company name | | sender.business_vat_number_code | Sender P.IVA | | recipient.business_name | Recipient company name | | recipient.business_vat_number_code | Recipient P.IVA | | notifications | Array of SDI notifications (type + date) |

The invoice_number, invoice_date, total_amount, and currency fields are computed by parsing the FatturaPA payload JSON on the server side, so they're available without transferring the entire payload.

Filtering by invoice series

Italian invoice numbers often include a series suffix (e.g. 1/Servizi, 2026/100/CI, 3/cipay). The API's invoice_number filter does a partial match, which can return unrelated series. The invoice_series parameter solves this by post-filtering results to match only invoices whose number ends with the exact series suffix:

# Only returns "1/Servizi", "2/Servizi", etc. -- not "2026/100/CI"
list_invoices(sender_vat: "01234567890", invoice_series: "Servizi")

# Only returns invoices in the /CI series
list_invoices(sender_vat: "01234567890", invoice_series: "CI")

The match is exact on the part after the last / in the invoice number.

Using the fields parameter

Both list_invoices and get_invoice accept an optional fields parameter to control which fields are returned:

# Default compact view (no fields parameter needed)
list_invoices(marking: "rejected")

# Request specific fields
list_invoices(marking: "rejected", fields: ["uuid", "notice", "recipient.business_name"])

# Request all fields (payload parsed + nulls stripped)
list_invoices(marking: "rejected", fields: ["*"])

# Get specific fields from a single invoice
get_invoice(uuid: "...", fields: ["payload", "sender", "recipient"])

The fields parameter supports dot-notation for nested objects (e.g., sender.business_name).

Tip: Prefer the default compact view or specific fields over ["*"]. Even with ["*"], the server parses payloads and strips nulls, but the full FatturaPA structure is still large. Use ["*"] only when you truly need the complete invoice data.

Pagination

list_invoices defaults to 10 items per page (items_per_page, max 30). Use the page parameter to navigate through results.

Estimated token savings

For a typical list_invoices call returning 10 invoices:

| Scenario | Without optimization | With optimization | |---|---|---| | Default view (compact fields) | ~25,000 tokens | ~1,500 tokens | | fields: ["*"] (full data) | ~25,000 tokens | ~10,000 tokens |

Key reductions with fields: ["*"]:

| Metric | Before | After | |---|---|---| | Null fields per invoice | ~60 | 0 (stripped) | | Payload encoding | Double-encoded string (\") | Parsed object (no escaping) | | Payload null fields | ~60 (hidden in string) | 0 (stripped) |

Usage Examples

Once the server is connected, you can ask Claude things like:

Invoicing

"Send this invoice to SDI for customer ACME Srl with P.IVA 01234567890"

"List all my invoices from January 2025 that were rejected"

"Show me invoice abc-123-def in XML format"

PDF Extraction

"Convert this PDF invoice to FatturaPA format"

"Check if my PDF extraction job is done yet"

Company Verification

"Look up the company with P.IVA 01234567890 -- I need their PEC and SDI code"

"Is this codice fiscale valid: RSSMRA85M01H501Z?"

"Does this company use split payment?"

Smart Receipts

"Issue an electronic receipt for 3 items totaling 45.50 EUR paid by card"

"Void receipt number 12345"

Notifications

"Show me all undownloaded SDI notifications"

"Are there any rejected notifications (NS type) from last week?"

Cassetto Fiscale

"Set up daily invoice downloads for fiscal ID 01234567890"

"Download all invoices from Q1 2025 for my company"

"How many rejected invoices do I have?"

Configuration

"List all my webhook configurations"

"Set up a webhook for new supplier invoices pointing to https://my-app.com/webhooks/acube"

"Show me all my business registry profiles"

Development

Setup

git clone https://github.com/nick-preda/mcp-server-acube.git
cd mcp-server-acube
npm install

Build

npm run build

Run in development mode

[email protected] ACUBE_PASSWORD=secret npm run dev

Test

npm test
npm run test:watch   # watch mode

Project Structure

src/
  index.ts                  # MCP server entry point, env validation, tool registration
  client.ts                 # A-Cube HTTP client with JWT authentication
  response.ts               # Response utilities: field picking, null stripping, formatting
  tools/
    invoices.ts             # send_invoice, send_simplified_invoice, list_invoices, get_invoice
    invoice-extract.ts      # extract_invoice_from_pdf, get_extraction_status, get_extraction_result
    notifications.ts        # list_notifications, get_notification, mark_notifications_downloaded
    verify.ts               # verify_fiscal_id, verify_company, verify_simple_company, verify_split_payment
    receipts.ts             # send_receipt, get_receipt_details, void_receipt, return_receipt_items
    webhooks.ts             # list/create/get/update/delete_webhook_config
    configurations.ts       # business registries + ADE appointees (list/create/get/update)
    cassetto-fiscale.ts     # download schedules, one-time downloads, rejected invoices
tests/
  client.test.ts            # API client tests
  tools/                    # Tool-specific tests

Reference

A-Cube API Environments

| Environment | Base URL (Gov.it) | Base URL (Common) | Purpose | |---|---|---|---| | sandbox | https://api-sandbox.acubeapi.com | https://common-sandbox.api.acubeapi.com | Testing and development | | production | https://api.acubeapi.com | https://common.api.acubeapi.com | Live invoicing via SDI |

The sandbox environment is used by default. Set ACUBE_ENVIRONMENT=production only when you are ready to send real invoices through SDI.

FatturaPA Document Types

| Code | Description | |---|---| | TD01 | Fattura (invoice) | | TD04 | Nota di credito (credit note) | | TD05 | Nota di debito (debit note) | | TD06 | Parcella (professional fee) | | TD07 | Fattura semplificata (simplified invoice) | | TD08 | Nota di credito semplificata | | TD09 | Nota di debito semplificata | | TD16 | Integrazione fattura reverse charge interno | | TD17 | Integrazione/autofattura acquisto servizi estero | | TD18 | Integrazione acquisto beni intracomunitari | | TD19 | Integrazione/autofattura acquisto beni art. 17 c.2 | | TD20 | Autofattura/regolarizzazione | | TD24 | Fattura differita (art. 21 c.4 lett. a) | | TD25 | Fattura differita (art. 21 c.4 terzo periodo lett. b) | | TD26 | Cessione beni ammortizzabili / passaggi interni | | TD27 | Fattura autoconsumo / cessioni gratuite senza rivalsa |

SDI Notification Types

| Code | Name | Description | |---|---|---| | NS | Notifica di Scarto | Invoice rejected by SDI due to validation errors | | MT | Metadati | Metadata file from SDI | | RC | Ricevuta di Consegna | Delivery receipt -- invoice successfully delivered to the recipient | | MC | Mancata Consegna | Non-delivery notification -- recipient's SDI channel unreachable | | EC | Esito Committente | Recipient outcome (accepted/refused by the recipient) | | SE | Scarto Esito | Outcome rejection by SDI | | NE | Notifica Esito | Outcome notification | | DT | Decorrenza Termini | Deadline passed -- 15 days without response, invoice considered accepted | | AT | Attestazione di Trasmissione | Transmission attestation |

SDI Invoice Statuses (marking)

| Status | Description | |---|---| | waiting | Invoice queued for submission to SDI | | quarantena | Invoice held in quarantine for review | | sent | Invoice submitted to SDI, awaiting notification | | invoice-error | Invoice processing error | | received | Incoming invoice received from SDI | | rejected | Invoice rejected by SDI (NS notification) | | delivered | Invoice delivered to recipient (RC notification) | | not-delivered | Invoice could not be delivered (MC notification) |

Webhook Event Types

The following events can be subscribed to via create_webhook_config:

| Event | Description | |---|---| | supplier-invoice | New supplier invoice received via SDI | | customer-invoice | Customer invoice sent via SDI | | customer-notification | SDI notification received for a customer invoice | | invoice-status-quarantena | Invoice entered quarantine status | | invoice-status-invoice-error | Invoice processing error | | legal-storage-missing-vat | Legal storage: missing VAT number | | legal-storage-receipt | Legal storage receipt generated | | receipt | Electronic receipt processed | | receipt-retry | Electronic receipt retry | | receipt-error | Electronic receipt error | | appointee | ADE appointee event | | sistemats-receipt-ready | SistemaTS receipt ready | | job | Asynchronous job completed |

Links

• npm package
• A-Cube API Documentation
• A-Cube Website
• Model Context Protocol (MCP)
• MCP TypeScript SDK
• Report Issues

License

MIT -- see LICENSE for details.

Copyright (c) 2026 Cipay Srl