MCP Server Acube

mcp服务器acube

](https://www.npmjs.com/package/mcp-server-acube)  

A. 模型上下文协议（MCP） 提供以下功能的服务器 38工具 用于与 A-卡套管API --意大利SDI（Sistema di Interscambio）、FatturaPA、智能收据、公司验证等电子发票平台。

将此服务器连接到Claude Desktop、Claude Code或任何兼容MCP的客户端，以通过自然语言管理意大利电子发票。

特性

• 电子发票 --通过SDI发送、列出和检索FatturaPA发票，支持JSON、XML、PDF和HTML格式
• AI驱动的PDF提取 --使用A-Cube的AI提取管道将PDF发票转换为FatturaPA格式
• 智能收据 --签发、作废和管理电子收据（scontrini elettronici）
• 公司验证 --通过P.IVA或codice fiscale查找意大利公司，验证财务ID，并检查拆分付款状态
• SDI通知 --监控收货、拒收和所有其他SDI通知类型
• 税务抽屉 --从Agenzia delle Entate税务抽屉安排定期或一次性批量下载
• 网络钩子 --为13种不同的事件类型配置实时事件回调
• 商业登记处和ADE任命人 --管理公司简介和财务中介配置
• 令牌优化响应 --紧凑的JSON输出，具有空剥离和字段选择功能，可最大限度地减少LLM令牌消耗
• 自动身份验证 --JWT令牌管理，自动刷新（24小时令牌生命周期）
• 沙箱和生产 --在A-Cube沙盒和生产环境之间无缝切换

快速开始

先决条件

你需要一个 A-卡套管API 账户注册地址： acubeapi.com 以获取您的凭据。

克劳德桌面

将以下内容添加到您的Claude Desktop配置文件中(claude_desktop_config.json):

{
  "mcpServers": {
    "acube": {
      "command": "npx",
      "args": ["-y", "mcp-server-acube"],
      "env": {
        "ACUBE_EMAIL": "your-email@example.com",
        "ACUBE_PASSWORD": "your-password",
        "ACUBE_ENVIRONMENT": "sandbox"
      }
    }
  }
}

克劳德代码

claude mcp add acube -- npx -y mcp-server-acube \
  -e ACUBE_EMAIL=your-email@example.com \
  -e ACUBE_PASSWORD=your-password \
  -e ACUBE_ENVIRONMENT=sandbox

或手动添加到 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "acube": {
      "command": "npx",
      "args": ["-y", "mcp-server-acube"],
      "env": {
        "ACUBE_EMAIL": "your-email@example.com",
        "ACUBE_PASSWORD": "your-password",
        "ACUBE_ENVIRONMENT": "sandbox"
      }
    }
  }
}

配置

服务器是通过环境变量配置的：

可用工具

发票（4个工具）

发票提取（3个工具）

通知（3个工具）

验证（4个工具）

智能收据（4个工具）

Webhooks（5个工具）

商业登记处和ADE任命人（8个工具）

卡式发票和拒收发票（7个工具）

响应优化

此服务器旨在最大限度地减少LLM令牌的消耗。每个响应都经过三个优化：

1.有效载荷解析

A-Cube API在 payload 现场。服务器会自动将此字符串解析为结构化对象，这使得空剥离可以在其中的~60个空字段上工作。这消除了双重编码开销(\" escapes），通常将有效载荷令牌的使用量减少约50%。

2.零剥离

全部 null 和 undefined 值会从响应中递归删除，包括在解析的有效载荷中。典型发票 sender 对象有大约40个字段，其中大约30个为空。剥离后，只剩下5-8个有人居住的油田。

3.压缩JSON

响应是序列化的，没有缩进(JSON.stringify(data) 而不是 JSON.stringify(data, null, 2)).这消除了不向LLM提供信息的空白标记。

4.默认字段选择打开 list_invoices

这 list_invoices 工具返回a 紧凑默认视图 （每页10个项目）而不是完整的A-Cube响应。原始API响应包括整个FatturaPA有效负载（每张发票约2000个令牌）和完整的发件人/收件人对象。紧凑视图仅提取基本字段：

这 invoice_number, invoice_date, total_amount，以及 currency 字段为 计算 通过在服务器端解析FatturaPA有效载荷JSON，因此它们可以在不传输整个有效载荷的情况下使用。

按发票系列筛选

意大利发票号码通常包含一系列后缀（例如。 1/Servizi, 2026/100/CI, 3/cipay).API的 invoice_number 过滤器进行部分匹配，可以返回不相关的序列。这 invoice_series 参数通过后过滤结果来解决这个问题，仅匹配编号以精确系列后缀结尾的发票：

# Only returns "1/Servizi", "2/Servizi", etc. -- not "2026/100/CI"
list_invoices(sender_vat: "01234567890", invoice_series: "Servizi")

# Only returns invoices in the /CI series
list_invoices(sender_vat: "01234567890", invoice_series: "CI")

这场比赛在最后一场之后的部分是精确的 / 在发票号码中。

使用 fields 参数

两者 list_invoices 和 get_invoice 接受可选 fields 用于控制返回哪些字段的参数：

# Default compact view (no fields parameter needed)
list_invoices(marking: "rejected")

# Request specific fields
list_invoices(marking: "rejected", fields: ["uuid", "notice", "recipient.business_name"])

# Request all fields (payload parsed + nulls stripped)
list_invoices(marking: "rejected", fields: ["*"])

# Get specific fields from a single invoice
get_invoice(uuid: "...", fields: ["payload", "sender", "recipient"])

这 fields 参数支持 点标记法 对于嵌套对象（例如。， sender.business_name).

提示： 更喜欢默认的紧凑视图或特定字段 ["*"].即使有 ["*"]，服务器解析有效载荷并删除空值，但完整的FatturaPA结构仍然很大。使用 ["*"] 只有当你真正需要完整的发票数据时。

分页

list_invoices 默认为 每页10个项目 (items_per_page，最多30）。使用 page 参数来浏览结果。

预计代币节省

对于典型 list_invoices 呼叫返回10张发票：

关键削减 fields: ["*"]:

用法示例

服务器连接后，您可以向Claude询问以下问题：

开具发票

“将客户ACME Srl的发票连同P.IVA 01234567890发送给SDI” “列出我从2025年1月起被拒绝的所有发票” “显示XML格式的发票abc-123-def”

PDF提取

“将此PDF发票转换为FatturaPA格式” “检查我的PDF提取工作是否已完成”

公司验证

“用P.IVA 01234567890查找公司——我需要他们的PEC和SDI代码” “此财政法典有效吗：RSSMRA85M01H501Z？” “这家公司使用分期付款吗？”

智能收据

“为3个项目开具电子收据，总计45.50欧元，通过卡支付” “无效收据编号12345”

通知

“显示所有未下载的SDI通知” “上周是否有任何被拒绝的通知（NS类型）？”

税务抽屉

“为会计ID 01234567890设置每日发票下载” “下载我公司2025年第一季度的所有发票” “我有多少张被拒绝的发票？”

配置

“列出我的所有webhook配置” “为指向的新供应商发票设置webhookhttps://my-app.com/webhooks/acube" “显示我的所有企业注册档案”

发展

设置

git clone https://github.com/nick-preda/mcp-server-acube.git
cd mcp-server-acube
npm install

构建

npm run build

以开发模式运行

ACUBE_EMAIL=you@example.com ACUBE_PASSWORD=secret npm run dev

测试

npm test
npm run test:watch   # watch mode

项目结构

src/
  index.ts                  # MCP server entry point, env validation, tool registration
  client.ts                 # A-Cube HTTP client with JWT authentication
  response.ts               # Response utilities: field picking, null stripping, formatting
  tools/
    invoices.ts             # send_invoice, send_simplified_invoice, list_invoices, get_invoice
    invoice-extract.ts      # extract_invoice_from_pdf, get_extraction_status, get_extraction_result
    notifications.ts        # list_notifications, get_notification, mark_notifications_downloaded
    verify.ts               # verify_fiscal_id, verify_company, verify_simple_company, verify_split_payment
    receipts.ts             # send_receipt, get_receipt_details, void_receipt, return_receipt_items
    webhooks.ts             # list/create/get/update/delete_webhook_config
    configurations.ts       # business registries + ADE appointees (list/create/get/update)
    cassetto-fiscale.ts     # download schedules, one-time downloads, rejected invoices
tests/
  client.test.ts            # API client tests
  tools/                    # Tool-specific tests

参考

A-Cube API环境

默认情况下使用沙盒环境。集 ACUBE_ENVIRONMENT=production 只有当您准备通过SDI发送真实发票时。

FatturaPA文件类型

SDI通知类型

SDI发票状态（标记）

Webhook事件类型

以下活动可以通过以下方式订阅 create_webhook_config:

链接

• A-Cube API文档
• A-Cube网站
• 模型上下文协议（MCP）
• MCP TypeScript SDK
• 报告问题

许可证

麻省理工学院——见 许可证 了解详情。

版权所有（c）2026 Cipay有限公司