fattureincloud-mcp

fattureincloud-mcp

由 Mediaform s.c.r.l. 开发 — 意大利热那亚

MCP 服务可将 Claude（桌面版、Code 或任何 MCP 客户端）连接到 FattureInCloud，这是意大利领先的电子发票 SaaS。通过自然语言管理发票、贷项通知单、形式发票、客户、供应商、成本／收入中心以及供应商费用。意大利要求通过 Sistema di Interscambio（SDI）进行 B2B／B2C 电子发票开具 — 此服务将 AI 辅助计费引入这一受合规要求驱动的工作流。

⚠️ 非官方集成。 与 FattureInCloud 商标所有者 TeamSystem S.p.A. 无关联，也未获得其认可或赞助。此处使用该商标仅作描述用途。

功能（23 个工具）

工具	描述
list_invoices	按年份／月份列出已开具的发票／贷项通知单／形式发票
get_invoice	按 ID 获取完整单据详情
get_pdf_url	获取单据的 PDF URL 和网页链接
list_clients	列出客户，可选筛选条件
get_company_info	获取已连接公司的信息
create_client	创建新客户
update_client	更新现有客户
create_invoice	创建发票草稿（可选 revenue_center）
create_credit_note	创建贷项通知单草稿（可选 revenue_center）
create_proforma	创建形式发票草稿（可选 revenue_center）
convert_proforma_to_invoice	将形式发票转换为电子发票草稿（可选 revenue_center）
update_document	部分更新草稿单据（可选 revenue_center）
duplicate_invoice	以新日期复制发票（可选 revenue_center）
delete_invoice	删除草稿单据
send_to_sdi	将发票／贷项通知单发送至意大利电子发票系统（SDI）
get_invoice_status	获取单据的电子发票状态
send_email	通过电子邮件发送副本（仅供参考）
list_received_documents	列出供应商单据（存在时会显示 cost_center）
get_received_document	按 ID 获取已收单据的完整详情
create_received_document	创建被动单据／费用（可选 cost_center）
list_cost_centers	列出已配置的成本／收入中心
get_situation	年度仪表板：净收入、已收款、未收款、成本、利润
check_numeration	检查发票编号的连续性

有意不提供将付款标记为“已支付”的功能：FattureInCloud API 要求指定付款账户，而无法通过 SDK 可靠地获取该账户。请使用 FattureInCloud 网页面板执行此操作。

安装

选项 1 — Claude Desktop（MCPB 套件，推荐）

1. 从 GitHub Releases 页面下载最新的 fattureincloud.mcpb。
2. 将 .mcpb 文件拖放到 Claude Desktop，或使用 设置 → 扩展 → 从文件安装。
3. 按提示填写 FattureInCloud API 令牌、公司 ID，以及（可选的）发件人电子邮件。

完成 — 无需配置 Python，也无需虚拟环境。

选项 2 — 通过 PyPI 手动安装

适用于 Claude Code 用户，或任何可读取 claude_desktop_config.json 样式配置的 MCP 客户端：

pip install fattureincloud-mcp

然后将其添加到 MCP 客户端配置中（对于 Claude Desktop，macOS 上的配置文件为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "fattureincloud": {
      "command": "python",
      "args": ["-m", "fattureincloud_mcp"],
      "env": {
        "FIC_ACCESS_TOKEN": "a/xxxxx.yyyyy.zzzzz",
        "FIC_COMPANY_ID": "123456",
        "FIC_SENDER_EMAIL": "[email protected]"
      }
    }
  }
}

编辑配置后，重启 MCP 客户端。

配置

环境变量	必填	描述
FIC_ACCESS_TOKEN	是	个人 API 访问令牌（以 a/ 开头）
FIC_COMPANY_ID	是	数字形式的公司 ID，登录 FattureInCloud 后可在 URL 中查看
FIC_SENDER_EMAIL	send_email 必填	用于发送抄送的发件人邮箱
FIC_CACHE_DIR	否	覆盖缓存目录（默认值为 ~/.fattureincloud-mcp/cache）
FIC_CACHE_DISABLED	否	设为 1 以禁用本地缓存

**如何获取 FattureInCloud 凭据：**登录 FattureInCloud，进入 Settings → API and Integrations，创建一个具有所需权限的 Manual Token。选择公司后，COMPANY_ID 位于 URL 中 /c/ 之后。

使用示例

示例 1 — 为已知客户创建发票

“查找客户 ‘Acme Srl’，并为其创建一张草稿发票：2026 年 11 月的咨询服务，金额 €1,500 + VAT，30 天后付款，收入中心为 ‘Project Alpha’。”

Claude 将：

1. 调用 list_clients（使用缓存），并选择匹配的客户
2. 调用 list_cost_centers（使用缓存），确认 Project Alpha 存在
3. 使用 client_id、项目、日期、付款条款和 revenue_center="Project Alpha" 调用 create_invoice
4. 返回草稿编号，并询问是否将其发送至 SDI

示例 2 — 成本中心分析

“我在 2025 年通过 ‘Project Alpha’ 收入中心开了多少账单？按月细分。”

Claude 将：

1. 调用 list_cost_centers，确认标签
2. 调用 list_invoices 查询 2025 年的发票（如果设置了 revenue_center，结果会包含每张发票对应的值）
3. 筛选 revenue_center == "Project Alpha" 并按月汇总

示例 3 — 重复创建定期发票

“复制 2025 年 10 月开给 ‘Recurring Customer Co’ 的每张发票，将新日期设为 11 月，并保留 30 天的付款期限。”

Claude 将：

1. 使用 query="Recurring Customer Co"、month=10 和 year=2025 调用 list_invoices
2. 对每条结果调用 duplicate_invoice，将 new_date 设为 11 月的日期
3. 返回新建的草稿发票列表，并在发送前征求确认

缓存

为尽量减少对 FattureInCloud API 的重复调用，此服务会将客户查询结果和成本中心列表作为 JSON 文件缓存在本地（默认位置为 ~/.fattureincloud-mcp/cache/，按 company_id 区分，缓存有效期为 24 小时）。缓存过程是透明的：工具签名不会改变。

# Force refresh:
rm -rf ~/.fattureincloud-mcp/cache

# Disable temporarily:
export FIC_CACHE_DISABLED=1

成本中心 / 收入中心

FattureInCloud 使用同一个注册表管理成本中心（用于供应商单据）和收入中心（用于已开具的单据）。使用此服务，你可以：

• list_cost_centers — 读取注册表
• revenue_center="<label>" — 在 create_invoice、create_credit_note、create_proforma、convert_proforma_to_invoice、update_document、duplicate_invoice 中指定收入中心
• cost_center="<label>" — 在 create_received_document 中指定成本中心

标签必须已存在；可在 FattureInCloud 网页界面中管理中心（Settings → Cost Centers）。传入未知标签时，错误消息会返回有效标签列表。

隐私与数据处理

• API 调用会从你的设备直接发送至 FattureInCloud 的服务器（api-v2.fattureincloud.it）。数据不会经由 Mediaform 或任何第三方服务器传输。
• 本地缓存以明文 JSON 格式存放在你的主目录中，由你自行管理。
• 凭据仅保存在你的 .env（已加入 gitignore）、shell 或 MCP 客户端 user_config 中。它们绝不会被记录日志，也不会传输给 FattureInCloud 以外的任何对象。
• 完整隐私政策：https://media-form.it/privacy-policy.html
• 另请参阅 docs/PRIVACY.md，其中提供了该政策的副本。

已知问题

• 部分客户端可能无法复制发票。 特定的客户端配置会触发尚未复现的故障路径。解决方法：在 FattureInCloud 网页面板中手动复制。相关问题记录在 docs/KNOWN_ISSUES.md 中——请通过 GitHub issues 报告可复现的情况。

贡献

欢迎通过 https://github.com/aringad/fattureincloud-mcp 提交问题和拉取请求。

进行任何代码更改时：

1. 从 main 分叉并创建分支（feat/...、fix/...、docs/...）。
2. 运行 pytest tests/——全部 39 项测试都必须通过。
3. 针对成本中心、缓存或新工具编写的新代码应附带测试（新模块的覆盖率目标为 ≥80%）。
4. 遵循 Conventional Commits 风格（feat:、fix:、docs:、chore:、test:）。
5. 提交 PR。维护者会根据 FattureInCloud API 契约审查更改。

安全

如需披露漏洞，请参阅 SECURITY.md。首选渠道：GitHub Security Advisories。

许可证

MIT——请参阅 LICENSE。

商标

“FattureInCloud”是 TeamSystem S.p.A. 的商标。这是一个由社区独立构建的集成项目，与 TeamSystem S.p.A. 无关联，也未获得其认可或赞助。使用该商标仅用于描述（指明本软件进行互操作的第三方服务）。

作者 / 支持

• 维护者：Mediaform s.c.r.l. ——意大利热那亚
• 问题反馈：https://github.com/aringad/fattureincloud-mcp/issues
• 电子邮件：[email protected]