{ "markdown": "# fattureincloud-mcp\n\n[![PyPI](https://img.shields.io/pypi/v/fattureincloud-mcp)](https://pypi.org/project/fattureincloud-mcp/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![MCPB](https://img.shields.io/badge/MCPB-compatible-blue)](https://github.com/modelcontextprotocol/mcpb)\n[![Listed in italia-mcp-servers](https://img.shields.io/badge/listed%20in-italia--mcp--servers-blue)](https://github.com/bsab/italia-mcp-servers)\n\n\n\nby **[Mediaform s.c.r.l.](https://media-form.it)** — Genova, Italy\n\nMCP server that connects Claude (Desktop, Code, or any MCP client) to **FattureInCloud**, the leading Italian SaaS for electronic invoicing. Manage invoices, credit notes, proformas, clients, suppliers, cost/revenue centers, and supplier expenses through natural language. Italy mandates B2B/B2C e-invoicing through the Sistema di Interscambio (SDI) — this server brings AI-assisted billing to that compliance-driven workflow.\n\n> ⚠️ **Unofficial integration.** Not affiliated with, endorsed by, or sponsored by TeamSystem S.p.A., owner of the FattureInCloud trademark. The trademark is used here for descriptive purposes only.\n\n## Features (23 tools)\n\n| Tool | Description |\n|------|-------------|\n| `list_invoices` | List issued invoices / credit notes / proformas by year / month |\n| `get_invoice` | Full document detail by ID |\n| `get_pdf_url` | PDF URL and web link for a document |\n| `list_clients` | List clients with optional filter |\n| `get_company_info` | Connected company info |\n| `create_client` | Create a new client |\n| `update_client` | Update an existing client |\n| `create_invoice` | Create a draft invoice (optional `revenue_center`) |\n| `create_credit_note` | Create a draft credit note (optional `revenue_center`) |\n| `create_proforma` | Create a draft proforma (optional `revenue_center`) |\n| `convert_proforma_to_invoice` | Convert a proforma into a draft electronic invoice (optional `revenue_center`) |\n| `update_document` | Partial update of a draft document (optional `revenue_center`) |\n| `duplicate_invoice` | Duplicate an invoice with a new date (optional `revenue_center`) |\n| `delete_invoice` | Delete a draft document |\n| `send_to_sdi` | Send invoice / credit note to the Italian e-invoice system (SDI) |\n| `get_invoice_status` | E-invoice status for a document |\n| `send_email` | Send a courtesy copy by email |\n| `list_received_documents` | List supplier documents (exposes `cost_center` when present) |\n| `get_received_document` | Full detail of a received document by ID |\n| `create_received_document` | Create a passive document / expense (optional `cost_center`) |\n| `list_cost_centers` | List configured cost / revenue centers |\n| `get_situation` | Yearly dashboard: net revenue, collected, outstanding, costs, margin |\n| `check_numeration` | Verify invoice numbering continuity |\n\n> Marking payments as \"paid\" is intentionally not exposed: the FattureInCloud API requires a payment account that cannot be reliably retrieved through the SDK. Use the FattureInCloud web panel for that operation.\n\n## Installation\n\n### Option 1 — Claude Desktop (MCPB bundle, recommended)\n\n1. Download the latest `fattureincloud.mcpb` from the [GitHub Releases page](https://github.com/aringad/fattureincloud-mcp/releases/latest).\n2. Drag the `.mcpb` file onto Claude Desktop, or use **Settings → Extensions → Install from file**.\n3. When prompted, fill in your FattureInCloud API token, company ID, and (optional) sender email.\n\nThat's it — no Python setup, no virtualenv.\n\n### Option 2 — Manual install via PyPI\n\nFor Claude Code users or any MCP client that reads `claude_desktop_config.json`-style configuration:\n\n```bash\npip install fattureincloud-mcp\n```\n\nThen add to your MCP client configuration (for Claude Desktop, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n \"mcpServers\": {\n \"fattureincloud\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"fattureincloud_mcp\"],\n \"env\": {\n \"FIC_ACCESS_TOKEN\": \"a/xxxxx.yyyyy.zzzzz\",\n \"FIC_COMPANY_ID\": \"123456\",\n \"FIC_SENDER_EMAIL\": \"billing@yourcompany.com\"\n }\n }\n }\n}\n```\n\nRestart your MCP client after editing the config.\n\n## Configuration\n\n| Env var | Required | Description |\n|---|---|---|\n| `FIC_ACCESS_TOKEN` | yes | Personal API access token (starts with `a/`) |\n| `FIC_COMPANY_ID` | yes | Numeric company ID, visible in the URL when logged into FattureInCloud |\n| `FIC_SENDER_EMAIL` | required for `send_email` | Sender mailbox for courtesy copies |\n| `FIC_CACHE_DIR` | no | Override cache directory (default `~/.fattureincloud-mcp/cache`) |\n| `FIC_CACHE_DISABLED` | no | Set to `1` to disable the local cache |\n\n**How to get the FattureInCloud credentials:** log into [FattureInCloud](https://secure.fattureincloud.it/), go to *Settings → API and Integrations*, create a **Manual Token** with the permissions you need. The `COMPANY_ID` is in the URL after `/c/` once you select a company.\n\n## Usage examples\n\n### Example 1 — Create an invoice for a known client\n\n> \"Find client 'Acme Srl' and create a draft invoice for €1,500 + VAT for consulting services in November 2026, payable in 30 days, on revenue center 'Project Alpha'.\"\n\nClaude will:\n1. Call `list_clients` (cached) and pick the matching client\n2. Call `list_cost_centers` (cached) to validate `Project Alpha` exists\n3. Call `create_invoice` with `client_id`, items, dates, payment terms, and `revenue_center=\"Project Alpha\"`\n4. Return the draft number and ask whether to send it to SDI\n\n### Example 2 — Cost-center analysis\n\n> \"How much did I bill on the 'Project Alpha' revenue center in 2025? Break down by month.\"\n\nClaude will:\n1. Call `list_cost_centers` to confirm the label\n2. Call `list_invoices` for year 2025 (the result includes `revenue_center` per invoice when set)\n3. Filter by `revenue_center == \"Project Alpha\"` and aggregate by month\n\n### Example 3 — Recurring invoices replay\n\n> \"Duplicate every invoice issued to 'Recurring Customer Co' in October 2025, set the new dates in November, keep 30-day payment terms.\"\n\nClaude will:\n1. Call `list_invoices` with `query=\"Recurring Customer Co\"` and `month=10`, `year=2025`\n2. For each result, call `duplicate_invoice` with `new_date` set in November\n3. Return the list of new draft invoices and ask before sending\n\n## Caching\n\nTo minimize redundant calls to the FattureInCloud API, this server caches client lookups and the cost-centers list locally as JSON files (default location `~/.fattureincloud-mcp/cache/`, scoped per `company_id`, 24-hour TTL). The cache is transparent: tool signatures don't change.\n\n```bash\n# Force refresh:\nrm -rf ~/.fattureincloud-mcp/cache\n\n# Disable temporarily:\nexport FIC_CACHE_DISABLED=1\n```\n\n## Cost / Revenue Centers\n\nFattureInCloud uses one shared registry for cost centers (on supplier documents) and revenue centers (on issued documents). With this server you can:\n\n- `list_cost_centers` — read the registry\n- `revenue_center=\"