Fatture in Cloud

fattureincloud-mcp

面向 Fatture in Cloud 的 MCP 服务：通过与 Claude（或任何 MCP 客户端）对话来管理开票，而不是在界面中点击操作。

它能实现应用本身做不到的事：

• 定期发票。“每月 5 日，重新开具发票给 Acme，主题注明上个月，发送到 SdI 并通过电子邮件发送。”Fatture in Cloud 没有原生功能支持此操作。
• **真正的复制。**复制发票，同时更新日期、递增编号、重新计算到期日、印花税和收款账户，只修改你指定的明细行。
• **批量操作。**通过一条命令复制、发送到 SdI、通过电子邮件发送或将数十张发票标记为已付款；操作前必须预览。
• 检查和报告。按客户统计逾期应收款、按月统计开票额和收款额、查看距简化税制门槛（85,000 €，按收付实现制）的差额、缺少印花税的发票、未发送或被拒的电子发票，以及编号缺口。
• **银行对账。**上传银行对账单（Intesa、UniCredit、Fineco、BPER、Poste、ING、Revolut、N26、Qonto 或任何 CSV/XLSX 文件），或者通过 PSD2 关联账户；每笔转账都会与正确的发票匹配，并按其日期登记为收款。
• **现金流预测。**逐月查看预期收款、定期发票、税务截止日期和固定支出，以及每月需要预留的金额，以确保 6 月和 11 月资金充足。
• **给会计师的资料包。**一个 ZIP 文件，包含 CSV、PDF、XML 和年度汇总。
• **简化税制税款。**根据实际收款额估算替代税和 INPS 缴款：计算 6 月 30 日（余额和第 1 期预缴）及 11 月 30 日（第 2 期预缴）应缴金额、年度总额和应预留的比例。
• **完整的 API v2。**已开具和已收到的单据、客户、供应商、产品、收据、F24、档案、日记账、附件、回收站和设置。没有专用工具的功能可通过 api_request 调用。

English: MCP server for the Italian invoicing SaaS Fatture in Cloud. Recurring invoices, real document duplication, bulk e-invoice (SdI) sending, receivables and regime forfettario reports, plus full CRUD over the v2 API. Tool descriptions are in Italian because the domain is Italian.

可以提出的请求示例

• “用今天的日期重新开具 9 月的所有发票，先给我看预览。”
• “为 Acme 设置每月 5 日开具固定金额的发票，发送到 SdI 并通过电子邮件发送。”
• “还有谁没付款？把第 26 号标记为已付款，收款日期为昨天。”
• “距离简化税制门槛还差多少？照这个速度会超吗？”
• “把第 12 号形式发票转成电子发票，并验证 XML。”
• “有没有金额超过 77,47 € 但没有印花税的发票？”
• “把 10 月发票的 PDF 下载到 ~/Documenti/fatture。”
• “我在 6 月 30 日和 11 月 30 日要交多少税？每张发票要预留多少？”
• “这是 Intesa 的银行对账单（~/Downloads/movimenti.xlsx）：把已收款的发票标记为已付款。”
• “到 11 月时，账户里的钱够付预缴款吗？每月要存下多少？”
• “把税务截止日期添加到我的日历和 Fatture in Cloud 的 F24 中。”
• “为会计师准备 2026 年资料包。”
• “登记从 SdI 收到的供应商发票，并选择正确的类别。哪些定期支出增加了？”

安装

需要 Node.js 20 或更高版本。

1. Token

在 Fatture in Cloud 中：

1. 打开 设置 → 应用和 API（开发者区域），并创建一个私有应用，例如 mcp-fattureincloud。
2. 在“身份验证和访问”中，只勾选“个人令牌”，并取消勾选 OAuth 2.0：这样就不需要 Redirect URL。保存。
3. 在应用页面生成令牌：选择公司和权限。至少需要对已开具的单据和客户拥有读取和写入权限；对于报表和税务，只需对其余资源拥有读取权限；对于你希望管理的其他资源，请添加写入权限。
4. 复制令牌：之后将不会再显示。不要把它粘贴到聊天中。将其放入 MCP 客户端配置，或放入 ~/.config/fattureincloud-mcp/.env。

个人令牌不会过期，可在同一页面撤销（官方指南）。

2. MCP 客户端

Claude Desktop，一键安装。 从最新的 release 下载 fattureincloud-mcp-x.y.z.mcpb，双击打开，并在提示时粘贴令牌。无需修改配置文件，令牌会保存到系统钥匙串中。

Claude Code

claude mcp add --scope user fattureincloud -e FIC_ACCESS_TOKEN=il-tuo-token -- npx -y fattureincloud-mcp

手动配置（claude_desktop_config.json、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "fattureincloud": {
      "command": "npx",
      "args": ["-y", "fattureincloud-mcp"],
      "env": { "FIC_ACCESS_TOKEN": "il-tuo-token" }
    }
  }
}

更多示例见 examples/。在软件包发布到 npm 之前，请用 github:NiccoloSalvini/fattureincloud-mcp 替代 fattureincloud-mcp。

变量

变量
FIC_ACCESS_TOKEN	必填
FIC_COMPANY_ID	可选：如果令牌只能访问一家公司，则会自动选择该公司；否则，每个工具都接受 company_id
FIC_TOOLSETS	可选：仅加载部分工具组，例如 documents,automation,reports,taxes,bank（见下文）。共有 123 个工具：工具组越少，模型的选择越准确，消耗的上下文也越少。
FIC_QUOTA_RESERVE	可选：预留的每小时请求数（默认值为 25）。API 每小时允许 1,000 次请求、每月允许 40,000 次请求，这些额度由各私有应用共享；服务会在每次响应时读取计数器，并在额度耗尽前停止。api_quota 会显示剩余请求数
FIC_MCP_DATA_DIR	用于保存定期任务的目录，默认值为 ~/.config/fattureincloud-mcp

变量也可以放在 ~/.config/fattureincloud-mcp/.env 中，格式为 FIC_ACCESS_TOKEN=...。建议在计划任务中使用这种方式。

定期发票

Fatture in Cloud 没有计划功能，因此定期任务保存在你的电脑上，位于 ~/.config/fattureincloud-mcp/schedules.json，并由每日任务执行。

1. 请 Claude 创建一项定期任务，例如使用提示词 nuova_ricorrenza。每项定期任务包含：

   • 一个模板单据，每次到期时都会复制该单据；
   • 一个频率：每 N 个月一次，指定某一天，其中 31 表示当月最后一天；
   • 一个操作：create 会创建待检查和发送的发票（如果金额会变化，建议使用此选项），create_and_send_sdi 会验证 XML 并发送；
   • 可选的客户电子邮件；
   • 修改项：行、金额和带占位符的文本。

2. 安装任务（只需一次）：

   npm i -g fattureincloud-mcp
   

   fattureincloud-mcp install-scheduler --hour 8
   

   在 macOS 上会创建一个 LaunchAgent，每天早晨运行并发送结果通知。如果 Mac 处于睡眠状态，任务会在唤醒时运行；如果 Mac 已关机，发票会在下次运行时创建。在 Linux 上会打印需要添加到 crontab 的行。

实用命令：

fattureincloud-mcp schedules

fattureincloud-mcp run-due --dry-run

占位符可用于主题、备注和行：{{mese}}、{{anno}}、{{mese_precedente}}、{{anno_mese_precedente}}、{{mese_successivo}}、{{trimestre}}、{{data}}。添加 |maiuscolo 可将首字母大写。例如，Consulenza {{mese_precedente}} {{anno_mese_precedente}} 在 11 月 5 日会变成“Consulenza ottobre 2026”。

保障措施：

• 每项定期任务每个到期日最多生成一份单据：会在创建发票之前保存下一个日期，并通过锁防止任务与 Claude 重叠运行。如果出现问题，发票不会生成，也不会重复创建，错误会保留在历史记录中。
• 如果电脑关机错过多个周期，重启后只会创建一份日期为今天的单据，而不是为每个逾期周期各创建一份。因此，编号会保持时间顺序。
• 如果 XML 验证失败，发票会创建但不会发送，并会报告错误。

工具

共 123 个工具，分为多个组，可通过 FIC_TOOLSETS 启用。admin 组始终处于启用状态。

documents：已开具的单据

• list_/get_/create_/update_/delete_issued_document(s)
• duplicate_document：复制单据并设置新的日期、编号、到期日和修改项
• transform_document：形式发票 → 发票、报价单 → 订单或发票、送货单 → 发票
• join_documents：将多个送货单、订单或报价单合并为一份单据
• mark_paid / mark_unpaid
• email_document
• verify_einvoice、send_einvoice（支持 dry_run）、get_einvoice_xml、einvoice_rejection_reason
• create_credit_note：创建全部或部分贷项通知单，并按 SdI 的要求关联到原始发票
• preview_totals：预览由 Fatture in Cloud 计算的总额（附加费、增值税、预扣税、印花税、分期付款），无需创建单据；duplicate_document 的预览也会使用此工具
• get_document_pdf：获取链接或下载 PDF
• upload_attachment
• get_new_document_defaults：获取下一个编号和默认值
• list_deleted_documents、recover_document

automation：批量操作和定期任务

• bulk_duplicate、bulk_send_einvoice、bulk_email：默认启用 dry_run；接受 ID 列表或筛选条件
• schedule_create、schedule_list、schedule_get、schedule_update、schedule_delete
• schedule_run_due、schedule_run_now

reports

• receivables_report：未结应收款、按逾期时长划分的逾期款项、按客户统计
• revenue_summary：按月和客户统计的营业额（权责发生制）与已收款项（收付实现制），包括小规模纳税人营业额门槛及预测
• audit_documents：未发送或被拒绝的电子发票、缺失的印花税、逾期付款、编号
• client_statement：客户对账单 税务
• tax_profile_set、tax_profile_get：系数、税率、社保缴款、实际缴款
• tax_estimate：6 月 30 日和 11 月 30 日的截止日期、年度总额、需预留的金额
• regime_simulator：根据你的数据比较简易税制、普通税制和 SRL
• stamp_duty_report：按季度统计虚拟印花税（F24 代码 2521-2524）；也会纳入截止日期
• quadro_lm：已结束年度纳税申报表中 LM 栏目的数值

规划

• cashflow_forecast：现金流预测和每月预留金额
• tax_deadlines_export：导出为 .ics，以及导出到 Fatture in Cloud 的 F24 中的税务截止日期
• accountant_package：提供给会计师的年度压缩包

银行

• bank_reconcile：将入账款项与发票匹配并登记收款
• bank_parse_statement、bank_formats
• bank_link_start、bank_link_finish、bank_accounts、bank_list_banks：通过 Enable Banking 建立 PSD2 连接

名录

• 对 clients、suppliers、products 以及设置 payment_accounts、payment_methods、vat_types 执行增删改查
• client_from_vat：通过 VIES 根据增值税号获取客户资料，并核验城市和省份
• lookup_city：根据邮政编码或名称查询市镇
• list_price_lists、get_price_list_items

收款文件：应付发票和费用

• 对 received_documents（费用、应付贷项通知单）执行增删改查
• list_pending_received_documents、get_pending_received_document：从 SdI 收到并等待登记的供应商发票
• register_pending_received_documents：将其登记为费用，并填写类别、分期和付款信息（默认启用 dry_run）
• suggest_expense_categories：根据供应商历史记录或关键词建议类别
• recurring_expenses_report：经常合作的供应商、预计下次发票时间、年度总额、涨价情况

会计：receipts_monthly_totals，以及对 receipts（销售额）、f24、archive_documents、cashbook_entries（日记账）执行增删改查

管理

• list_companies、get_company_info（也可查看套餐使用情况）
• api_quota：查询本小时和本月剩余的 API 请求次数
• lookup：增值税税率、付款方式、账户、成本和收入中心、类别、模板、货币、国家……
• list_sent_emails
• api_request：API v2 的任何其他端点

筛选器 q 使用 Fatture in Cloud 语法，例如 date >= '2026-01-01' and entity.name like '%rossi%' 或 amount_gross > 1000。

内置提示词

• chiusura_mese：完整的月末核查，不执行不可逆操作
• nuova_ricorrenza：引导创建周期性发票

Tasse（forfettario 税制）

tax_estimate 根据 Fatture in Cloud 中记录的收入，估算你需要缴纳多少税款以及何时缴纳。首先，只需通过 tax_profile_set 设置一次个人资料，例如向 Claude 询问：「我是参加 gestione separata 的专业人士，盈利系数为 78%，税率为 15%， partita IVA 于 2024 年开通。」

计算方式：

总收入	年收入 × 盈利系数（专业人士为 78%；根据 ATECO，其他系数为 67%、40%、86%、62%）
社保缴费	gestione separata 按总收入的 26.07% 计算；或者按 artigiani/commercianti 计算（固定金额加超额部分，可选择减免 35%）；或者缴纳职业社保基金
应税收入	总收入 − 当年已缴纳的社保缴费（上一年的余额 + 预缴款）
替代税	15%；符合条件时，前五年为 5%
6 月 30 日	上一年的余额 + 第 1 笔预缴款（税款和社保缴费）
11 月 30 日	第 2 笔预缴款
预缴款	税款：按上一年的 100% 分两期各缴 50%；低于 51.65 € 时无需预缴，低于 257.52 € 时于 11 月一次缴清；gestione separata：按 80% 分两期各缴 40%

对于本年度，收入会推算至年底；也可以只使用截至目前的收入（projection: "to_date"），或使用你自己的估算值（revenue_estimate）。如果你实际缴纳的金额与计算结果不同，或者在 Fatture in Cloud 之外还有收入，请按年份填入 overrides：这样估算就会准确。结果还会列出每笔收入建议预留的比例，并在预缴款超过税款时发出提醒；遇到这种情况，采用预估法可能更合适。

这只是用于规划现金流的估算，并非报税计算：税率和上限每年都会变化（默认值为 2025 年的数据，可在个人资料中修改）；付款前最好请税务顾问核查。

销项发票（普通税制）

供应商发票会从 SdI 进入 Fatture in Cloud 的待处理已收文档，并在你将其登记为支出前一直保留在那里。服务器会批量处理：

1. list_pending_received_documents 列出供应商、日期、编号、不含税金额、IVA、总额、到期日以及是否有 XML。默认显示从 SdI 收到的发票（source: "agyo"）；使用 all 还会包括通过电子邮件或浏览器上传的发票。
2. suggest_expense_categories 提供类别建议：优先采用过去 24 个月内为同一供应商（先按 P.IVA，再按名称）使用过的类别，否则根据名称和描述应用规则（能源和燃气 → 公用事业，TIM/Vodafone/Iliad/Fastweb → 电话和互联网，Aruba/Google/AWS/Microsoft/GitHub/OpenAI/Anthropic → 软件和云服务，ENI/Q8 → 燃料，Amazon → 采购，会计师 → 咨询，租赁 → 租金）。每项建议都附有置信度和理由，并尽可能使用已有类别：例如，在 Fatture in Cloud 的预设类别中，公用事业归入「服务和建筑物」，软件归入「服务器和托管」。
3. register_pending_received_documents 创建支出。每笔支出都会关联到待处理文档（pending_id），这样 Fatture in Cloud 会保留 XML 和附件。分期付款始终覆盖含税总额，因为 API 会拒绝付款不完整的支出。使用 paid、paid_date 和 payment_account_id 可将支出登记为已付款。操作默认以预览模式开始。remove_pending 也会从待处理列表中删除文档：API 的公开规范没有记录此操作，因此如果删除被拒绝，支出仍会创建，结果中会对此进行说明。

recurring_expenses_report 分析过去 12 个月的支出，并找出至少有三张发票且开票周期规律的供应商：每月、每两个月（常见于水电账单）、每季度、每半年或每年。报告会列出每家供应商的平均金额、最近一张发票、预计下一张发票的时间以及估算年总额。报告还会标记金额比之前的平均值高出 10% 以上的发票，以及逾期超过 15 天的预期发票。

只需少量请求即可读取全部数据：列表每页 100 行，且没有逐个读取文档的调用。

在固定税率制度下，采购发票不产生税务影响（不能抵扣 IVA，也不能扣除成本）。不过，你仍然可以登记这些发票，以便归档和跟踪到期日。

银行：收款对账

bank_reconcile 获取银行流水，为每笔入账寻找对应的未结发票，并将其标记为已付款，使用入账日期作为付款日期。对于固定税率制度，该日期至关重要，因为税款按现金收付计算。

匹配。 每笔入账的评分依据如下：

标准	分数
金额与发票分期金额或剩余金额相同	+50
金额少于应付金额，差额不超过 2 €（未支付印花税或手续费）	+30
付款说明中包含发票编号（FT 26、fattura n. 26、26/2026）	+30
付款说明中包含客户的 P.IVA 或税号	+30
付款说明中包含客户名称	最高 +25
付款日期早于发票日期	−40

评分达到 75 分时置信度为高，达到 60 分时为中，低于 60 分时为低。每笔入账最多匹配一张发票。如果两张发票的评分相同，匹配置信度会降为中，并标记为有歧义。操作始终以预览模式开始：设置 dry_run: false 后，只会登记置信度至少达到 min_confidence 的匹配（默认值为 high）。对同一文件重复运行，不会重复登记同一笔收款。

来自文件（任意银行）

从网上银行下载交易记录列表，并传入文件路径。可自动识别的格式（bank_formats）：

银行	文件
Intesa Sanpaolo、Isybank	XLSX「Lista movimenti」，仅限已入账记录；CSV 入账／扣款
UniCredit	CSV
Fineco	XLSX 和 CSV
BPER	XLS「Movimenti Conto」
Poste Italiane / BancoPosta	XLSX
ING Italia	CSV
Revolut、N26、Qonto	CSV
其他	任意包含日期、金额（或收入和支出）及描述的 CSV/XLSX：自动识别列，或通过 mapping 指定

这些格式来自其他开源项目使用的实际导出文件（ynab-transformer、BananaAccounting、bankr.isp）。如果你的银行导出的是其他格式，请提交 issue，并附上列标题。

直接连接（PSD2，可选）

意大利银行（包括 Intesa）不向个人提供 PSD2 API：该接口仅向获授权的中介机构开放。可通过 Enable Banking 连接；它提供免费、非商业的个人使用模式，可连接你自己的账户。支持 Intesa Sanpaolo、UniCredit、BPER、Banco BPM、Poste、Fineco、ING、Mediolanum、Crédit Agricole、MPS 和 BCC。

1. 在 enablebanking.com/cp 注册并创建一个生产环境应用。将 https://localhost:8765/callback 设为重定向 URL：该地址无需实际存在。

2. 下载生成的 .pem 私钥，并通过「Activate by linking accounts」激活应用，同时连接你的账户。应用将进入 restricted 模式，只能访问你的账户。

3. 在 ~/.config/fattureincloud-mcp/.env 中：

   ENABLE_BANKING_APP_ID=...
   ENABLE_BANKING_KEY_PATH=~/.config/fattureincloud-mcp/enablebanking.pem
   ENABLE_BANKING_REDIRECT_URL=https://localhost:8765/callback
   

4. 告诉 Claude「连接我的 Intesa 账户」（bank_link_start）。打开链接，在银行应用中授权，然后粘贴最终页面的地址，即使浏览器报错也一样（bank_link_finish）。授权有效期最长为 180 天，之后需要续期。许多银行一次只允许有一项有效授权。

5. 之后只需运行 bank_reconcile，无需提供文件：它会读取已连接账户最近 90 天的记录。

会话保存在 bank-sessions.json 中，仅你的用户可读取。密钥保留在你的电脑上。

税制模拟器

regime_simulator 使用相同的收入和成本进行比较，计算不同税制下的实际所得：

• 定额税制：税率为 5% 或 15%；
• 普通税制：个人独资企业，按 23%／33%／43% 的累进税率缴纳 IRPEF，并计入自雇工作抵扣额和附加税；
• 单人 SRL：IRES 为 24%、IRAP 为 3.9%、股息税为 26%。系统会选择能降低税负的管理人薪酬，并计入公司的固定成本。

还会指出收入超过哪个水平后，定额税制将不再划算。

默认使用当年的预计收款额和税务资料中的参数。如果你处于前五年内，还会按 15% 的税率重复比较，以展示之后会有哪些变化。实际成本（costs）仅适用于普通税制和 SRL。这是按正常运营的一年进行的比较，可帮助你判断何时咨询会计师，而不是让你独自做决定。

规划

• cashflow_forecast：预测未来 12 个月逐月的收入和支出。统计待收款项（当月到期的款项）、按典型付款延迟计算的未来周期性发票、预计纳税期限和你填写的固定支出。使用 opening_balance 可获取预计余额和资金赤字月份的提醒。还会计算按时缴纳所有税款所需的最低每月预留金额；使用 tax_fund 可计入你已预留的金额。
• tax_deadlines_export：将预计纳税期限导出为 .ics 文件，并设置提前 7 天和 1 天的提醒，可导入 Calendario、Google 或 Outlook。还会在 Fatture in Cloud 的到期日程表中将这些期限创建为待缴 F24。再次运行时会更新金额，而不会重复创建，也不会改动已缴纳的 F24。
• accountant_package：生成 commercialista-AAAA.zip，其中包含 fatture.csv、incassi.csv、crediti_aperti.csv 和 spese.csv（分隔符为 ;，小数点使用逗号，可直接在 Excel 中打开）、发票和贷项通知单的 PDF、FatturaPA XML，以及包含收入、forfettario 方案门槛、税款估算和检查结果的 riepilogo.md。

HTTP 服务

用于共享安装（团队、服务端、n8n……）：

fattureincloud-mcp http --port 3000 --host 0.0.0.0

服务为无状态，不会保存凭据。每个请求都需携带自己的凭据：Authorization: Bearer <token>（或 X-FIC-Token），以及（如有需要）X-FIC-Company。端点为 POST /mcp，状态检查端点为 GET /health。如果将其公开到 Internet，请置于 HTTPS 之后。

安全

• 向外部执行的操作（发送至 SdI、发送邮件）会标记为破坏性操作，因此 MCP 客户端会要求确认。批量工具会先以预览模式运行。
• 发送至 SdI 的电子发票无法删除：只能通过贷项通知单进行更正。因此，send_einvoice 始终会在发送前验证 XML。
• 令牌保存在你的计算机上，或者在 HTTP 模式下放在每个请求的标头中。周期性设置保存在本地 JSON 文件中。

开发

npm install

npm test

npm run build

node scripts/smoke.mjs 会使用仅限读取的工具在真实账户上测试服务（令牌位于 ~/.config/fattureincloud-mcp/.env）；node scripts/smoke.mjs <tool> '<json>' 会调用单个工具。

测试使用模拟的 Fatture in Cloud API（test/fake-api.ts），并通过内存中连接的真实 MCP 客户端运行，不会触碰你的账户。要使用真实账户测试，请使用测试公司和 dry_run。

结构：

• src/client.ts：API v2 的 HTTP 客户端（对 429 重试，提供易读的错误信息）
• src/copy.ts：复制逻辑和占位符
• src/schedules.ts、src/runner.ts：周期性设置
• src/reports.ts：应收款、收入、检查（纯函数）
• src/taxes.ts：forfettario 方案的税款和缴款模型
• src/expenses.ts：进项发票、支出类别和周期性支出（纯函数）
• src/cashflow.ts、src/ics.ts、src/accountant.ts：规划
• src/bank/：银行对账单解析器、匹配、Enable Banking 客户端
• src/tools/：工具定义；CRUD 由 crud.ts 中的表生成

发布

更新 package.json 中的 version，然后创建并推送标签：

git tag v0.3.0 && git push origin v0.3.0

GitHub Action release.yml 会运行测试，然后：

• 通过 trusted publishing 使用 OIDC 发布到 npm，无需令牌，并自动生成 provenance；
• 创建带有 .mcpb 扩展名的发行版（也可在本地通过 npm run build:mcpb 生成）；
• 在 MCP 注册表发布项目条目。

欢迎提交 PR。本项目与 Fatture in Cloud 或 TeamSystem 均无关联。

许可证

MIT