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
`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 local file, 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)

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 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.