Skip to main content
Glama
FattureInCloud MCP

FattureInCloud MCP

by badbat75

FattureInCloud MCP

MCP (Model Context Protocol) server for the Fatture in Cloud API v2. Lets Claude (Code / Desktop / any MCP client) read and manage (CRUD) issued documents (invoices, credit notes, quotes...) and received documents (expenses, passive credit notes...).

Two transports over the same tools: stdio as a local child process, and Streamable HTTP for a shared deployment that keeps no credentials of its own.

Tools

Tool

Description

list_companies

Companies accessible with the token (source of company_id)

get_company_info

Config lookups: VAT types, payment methods/accounts, expense categories

list_issued_documents

Paginated list of issued documents, one type per call (default invoice)

get_issued_document

Full detail of a single issued document

list_received_documents

Paginated list of received documents (default expense)

get_received_document

Full detail of a single received document

list_pending_received_documents

The "documenti da registrare" queue: SDI e-invoices (and emailed/uploaded documents) waiting to be registered

get_pending_received_document

Full detail of a single pending document

create_issued_document

Create an invoice, credit note, quote...

update_issued_document

Update an issued document (partial: only the fields passed)

delete_issued_document

Delete an issued document (irreversible)

create_received_document

Create an expense or other received document

update_received_document

Update a received document (partial)

delete_received_document

Delete a received document (irreversible)

upload_attachment

Upload a file from an https url (preferred remotely), content_base64, or a server-side file_path; returns an attachment_token to bind via create/update

delete_document_attachment

Remove a document's attachment (FIC API currently 500s here, see docs)

See docs/api.md for parameters, payload shapes and API quirks. List tools support:

  • q — Fatture in Cloud filter language, e.g. date >= '2026-01-01' and date <= '2026-06-30', entity.name like '%acme%', amount_gross > 1000

  • sort — e.g. -date (descending)

  • page / per_page (min 5, max 100) — responses include current_page, last_page, total

  • fieldset — basic (compact, default for lists) or detailed (includes line items)

Related MCP server: Pacioli

Setup

npm install
npm run build

Authentication

Two values, wherever they come from:

  • FIC_ACCESS_TOKEN (required) — a manual access token: generate it from the Fatture in Cloud developer area selecting the read scopes for issued and received documents. Manual tokens never expire (revocable from the same page).

  • FIC_COMPANY_ID (optional) — default company ID; if unset, tools require an explicit company_id argument (discover it with list_companies).

Over stdio they are environment variables of the server process. Over HTTP they are the X-FIC-Token and X-FIC-Company headers of each request, so the deployed instance stores neither.

Configuration templates for Claude Code, Claude Desktop and opencode, local stdio and remote HTTP, are in examples/.

Claude Code

A project-scoped .mcp.json (gitignored) holds the credentials. From any other directory:

claude mcp add --scope user fattureincloud -e FIC_ACCESS_TOKEN=<token> -e FIC_COMPANY_ID=<id> -- node <repo>\dist\index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "fattureincloud": {
      "command": "node",
      "args": ["<repo>\\dist\\index.js"],
      "env": {
        "FIC_ACCESS_TOKEN": "<token>",
        "FIC_COMPANY_ID": "<id>"
      }
    }
  }
}

Remote (Streamable HTTP)

dist/http.js serves the same tools over HTTP and takes the credentials from the X-FIC-Token and X-FIC-Company request headers instead of the environment, so the host running it stores no secret. ./scripts/deploy.ps1 (or ./scripts/deploy.sh) installs it as a systemd service on a remote machine — see docs/deploy.md.

Extending

The API surface is small on purpose. To add endpoints (clients, suppliers, products, receipts, taxes, cashbook...), follow the pattern in src/server.ts: one registerTool per action calling ficGet from src/fic.ts. The full OpenAPI spec lives at fattureincloud/openapi-fattureincloud.

Available Tools

14 tools
create_issued_documentCreate issued documentA

Create an issued document (invoice, credit note, quote...). Requires entity and items_list; look up VAT type and payment method/account IDs with get_company_info first. Returns the created document.

Inputs: data (required), company_id.

create_received_documentCreate received document (expense)A

Create a received document (expense, passive credit note...). Requires description, entity, date, amounts (amount_net/amount_vat/amount_gross) and a payments_list covering the total. Returns the created document.

Inputs: data (required), company_id.

delete_document_attachmentDelete document attachmentA
DestructiveIdempotent

Remove the attachment from an issued or received document (the document itself is untouched). Irreversible. Note: the FIC API has been observed returning 500 on this endpoint; deleting the document or replacing the attachment via update (new attachment_token) are alternatives.

Inputs: target (required), document_id (required), company_id.

delete_issued_documentDelete issued documentA
DestructiveIdempotent

Permanently delete an issued document by ID. Irreversible.

Inputs: document_id (required), company_id.

delete_received_documentDelete received document (expense)A
DestructiveIdempotent

Permanently delete a received document by ID. Irreversible.

Inputs: document_id (required), company_id.

get_company_infoGet company configuration listsA
Read-only

Look up company configuration needed to build documents: VAT types (IDs for items_list), payment methods, payment accounts, expense categories.

Inputs: resource (required), company_id.

get_issued_documentGet issued documentA
Read-only

Get a single issued document by ID with full details (entity, line items, payments, amounts).

Inputs: document_id (required), fieldset, company_id.

get_received_documentGet received document (expense)A
Read-only

Get a single received document (expense, passive credit note...) by ID with full details.

Inputs: document_id (required), fieldset, company_id.

list_companiesList companiesA
Read-only

List the Fatture in Cloud companies accessible with the configured token. Returns id, name and type for each company; the id is the company_id used by the other tools.

Inputs: no named parameters.

list_issued_documentsList issued documentsA
Read-only

List issued documents (invoices, credit notes, quotes, proformas, receipts...) for a company. One document type per call; defaults to invoices. Paginated: check current_page/last_page/total.

Inputs: q, page, sort, type, +3 more.

list_received_documentsList received documents (expenses)A
Read-only

List received documents for a company: expenses (spese), passive credit notes, passive delivery notes, self invoices. Defaults to expenses. Paginated: check current_page/last_page/total.

Inputs: q, page, sort, type, +3 more.

update_issued_documentUpdate issued documentA
DestructiveIdempotent

Update an existing issued document. Only the fields provided in data are changed. Fetch the document first with get_issued_document to see its current state.

Inputs: data (required), document_id (required), company_id.

update_received_documentUpdate received document (expense)A
DestructiveIdempotent

Update an existing received document. Only the fields provided in data are changed. Fetch the document first with get_received_document to see its current state.

Inputs: data (required), document_id (required), company_id.

upload_attachmentUpload document attachmentA

Upload a local file (PDF, image, XML, zip...) as an attachment for an issued or received document. Returns an attachment_token: pass it as data.attachment_token in a create/update tool to bind it to a document. Unbound tokens expire after a while, so upload right before creating/updating.

Inputs: target (required), file_path (required), filename, company_id.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource (issued document, received document, company, company info, attachment) and action (get, create, list, update, delete, upload, remove). The parallel issued/received sets are clearly separated by document type, and the attachment tools are distinct. No two tools could be confused for the same purpose.

    Naming Consistency4/5

    The core document tools follow a consistent verb_noun pattern: get_issued_document, create_received_document, list_issued_documents, etc. Minor deviations exist: 'get_company_info' and 'delete_document_attachment' use slightly different structures (info suffix, document_attachment compound). Overall, the pattern is predictable and readable.

    Tool Count5/5

    14 tools is well-scoped for a document management server. It covers two document types with full CRUD plus list, company management, configuration lookup, and attachment handling. Each tool has a clear role, and the count is not excessive or overly sparse.

    Completeness4/5

    The toolset provides complete CRUD and listing for both issued and received documents, plus company info and attachment upload/delete. A notable gap is the lack of a download attachment (or document PDF) function, which would be useful for a full document workflow, but the core lifecycle is covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      A Model Context Protocol (MCP) server for the Holded Invoice API. This server allows AI assistants like Claude to interact with Holded's invoicing, contacts, products, and more.
      119
      171 npm
      20
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that connects Claude Code to the Holded API for natural language financial, accounting, and invoicing queries, with built-in Spanish PGC context.
      13
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for the FreshBooks API that lets Claude read and manage invoices, clients, expenses, projects, services, payments, and time entries.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for interacting with Aruba Fatturazione Elettronica API, enabling users to manage electronic invoices with Claude, including sending invoices to SDI, searching, downloading, and retrieving invoice details and notifications.
      6
      7
      MIT