pop-mcp

pop-mcp

适用于 POP 的 MCP（模型上下文协议）服务 — 让大模型能够直接通过 AI 助手生成、提交和管理意大利电子发票（FatturaPA/SdI）、Peppol、KSeF、ZUGFeRD/Factur-X 和 PDF 发票。

npm： @getpopapi/pop-mcp · 远程服务： https://mcp.popapi.io/mcp

---

远程 MCP（HTTP）—最快上手方式

不想安装任何东西？pop-mcp 作为托管的多租户 MCP 服务运行于：

https://mcp.popapi.io/mcp

前往 popapi.io 获取许可证密钥，然后让任何支持 MCP 的客户端使用该密钥作为 Bearer 令牌连接到此 URL。无需本地安装，无需设置 POP_API_KEY 环境变量，也无需构建步骤 — 对大多数人来说，这是体验 pop-mcp 的推荐方式。只有在确实需要 Claude Desktop 配置来运行本机进程时，才使用下方的本地 stdio 配置。

工作原理

此端点支持 MCP 2026-07-28，这是完全无状态的：没有 initialize 握手，也无需打开或跟踪会话。每个请求都是独立完整的 — 请求会声明自己的协议版本和功能 — 服务会独立处理每个请求。正因如此，这是一个多租户端点：它不会从自身环境中读取固定的 POP_API_KEY。每个请求都必须携带你自己的 POP 许可证密钥作为 Bearer 令牌：

Authorization: Bearer <your_license_key>

如果缺少 Authorization 标头或其格式错误，服务会在进行任何 POP API 调用之前返回 401，并附带 error_code: "unauthorized_user"。格式正确但无效的密钥会直接传递给 POP API，并返回 POP 给出的错误（unauthorized_user、insufficient_level 等）— 服务本身不会重新验证密钥。

任何现代 MCP HTTP 客户端都可以连接：Claude（远程连接器）、OpenAI Responses API、n8n、MCP Inspector 或自定义集成 — 不仅限于 Claude Desktop。所有发票、状态、高级功能和引导工具均可使用；引导工具每次调用都使用自己的 onboarding_token，不需要 Bearer 密钥。

curl 示例

发现服务支持的协议版本和功能（可选 — 客户端也可以直接调用 tools/list 或 tools/call，并在调用过程中处理版本协商错误）：

curl -X POST https://mcp.popapi.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_license_key_here" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } }
  }'

列出可用工具 — 每个请求都是独立完整的，因此 _meta（协议版本 + 客户端功能）会随每次调用传递，而不只是首次调用：

curl -X POST https://mcp.popapi.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_license_key_here" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } }
  }'

无论许可证密钥为何，工具目录都相同，因此 tools/list 和 server/discover 响应会附带一小时的公共缓存提示（ttlMs: 3600000, cacheScope: "public"）— 客户端和网关可以跨租户缓存这些响应。

每个请求都必须包含 MCP-Protocol-Version 和 Mcp-Method（依据 SEP-2243），且必须与请求正文中的 _meta.protocolVersion 和 method 完全匹配，否则服务会以 400 和 JSON-RPC 错误 -32020（HeaderMismatch）拒绝请求。tools/call 请求还必须包含与 params.name 匹配的 Mcp-Name 标头。

MCP Inspector 示例

npx @modelcontextprotocol/inspector

将其配置为连接到 https://mcp.popapi.io/mcp，并设置标头 Authorization: Bearer <your_license_key>。

此端点以 Vercel 无服务器函数（api/mcp.ts → src/mcpHandler.ts）的形式运行。本地运行方式：npx vercel dev（需要先通过 vercel link 链接到项目）。

---

什么是 POP？

POP 是一项用于生成和发送电子发票的云服务，支持：

• 🇮🇹 意大利电子发票（FatturaPA/SdI） — 符合 D.Lgs. 127/2015
• 🇪🇺 Peppol — 泛欧洲跨境 B2B 发票（UBL 2.1）
• 📄 PDF 发票 — 支持品牌定制和邮件发送
• ✅ 验证 — 财政代码、增值税号、单据提交前检查
• 🗄️ 存档 — 意大利法定存档（conservazione sostitutiva）

---

可用工具（共 11 个）

发票创建

工具	端点	套餐
pop_create_sdi_invoice	POST /create-xml	任意
pop_create_peppol_invoice	POST /create-ubl	任意（提交需 Basic+）
pop_create_pdf_invoice	POST /create-pdf	任意（邮件发送需 Basic+）
pop_create_ksef_invoice	POST /create-ksef-xml	任意（通过服务提供商提交需配置 KSeF）
pop_create_zugferd_invoice	POST /create-zugferd	任意
pop_sync_zoho_document	POST /integration/zoho/sync	需要 Zoho 连接器

状态与检索

工具	端点	套餐
pop_get_invoice_status	POST /sdi/document-notifications	任意
pop_get_peppol_document	POST /peppol/document-get	Basic+
pop_get_sdi_document	POST /sdi/document-get	Basic+

验证与高级 SdI 功能

工具	端点	套餐
pop_verify_sdi_document	POST /sdi/document-verify	Basic+
pop_preserve_document	POST /sdi/document-preserve	Basic+

---

前置条件

• Node.js >= 20
• 一个 POP 许可证密钥
• 如需提交 SdI/Peppol：POP 账户中已启用集成（Basic/Growth 套餐）

---

身份验证

获取许可证密钥

初次使用 POP？ 请访问 popapi.io 创建账户并获取许可证密钥。

仅使用 API 的用户可通过以下流程激活账户并获取 license_key：

1. 打开 https://popapi.io/otp-login/
2. 输入电子邮箱地址
3. 通过邮件接收一次性密码（OTP）并输入
4. 完成配置向导
5. 打开 https://popapi.io/ → Account > API
6. 复制默认生成的 license_key

密钥管理

• 账户包含一个默认的 license_key，可在 Account > API 中查看
• 可在同一页面生成与该账户关联的其他密钥
• 每个 license_key 都必须作为机密凭据处理 — 请勿将其提交到源代码管理系统

建议的初始步骤

1. 获取 license_key
2. 使用 GET /account-profile 测试密钥
3. 使用实际负载发送一条文档生成请求
4. 确认本地生成正常后，再添加可选的发送集成

---

安装

从 npm 安装（推荐）

npm install -g @getpopapi/pop-mcp

从源代码安装

git clone https://github.com/getpopapi/pop-mcp
cd pop-mcp
npm install
npm run build

---

配置

将 POP 许可证密钥设置为环境变量：

export POP_API_KEY=your_license_key_here

可选 — 使用预发布环境：

export POP_ENVIRONMENT=staging

---

Claude Desktop 设置

将以下内容添加到 claude_desktop_config.json：

如果从 npm 安装：

{
  "mcpServers": {
    "pop": {
      "command": "pop-mcp",
      "env": {
        "POP_API_KEY": "your_license_key_here"
      }
    }
  }
}

如果从源代码运行：

{
  "mcpServers": {
    "pop": {
      "command": "node",
      "args": ["/path/to/pop-mcp/dist/cli.js"],
      "env": {
        "POP_API_KEY": "your_license_key_here"
      }
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

---

工具参考

license_key 始终会通过 POP_API_KEY 自动注入 — 请勿手动传入。

pop_create_sdi_invoice

生成意大利 FatturaPA XML 文档。可选择将其提交至 SdI（Sistema di Interscambio）。

MCP 输入：

参数	类型	必填	说明
data	对象	✅	完整发票数据（参见发票数据结构）
submit_to_sdi	布尔值	—	设为 true 可提交至 SdI。需要 Basic+ 计划，并启用 SdI 集成。默认值：false
integration	对象	—	覆盖集成配置。如果设置，则覆盖 submit_to_sdi。
environment	字符串	—	目标环境（例如 "sandbox"）

integration.use 的集成选项：

• "sdi-via-pop" 或 "sdi" — 通过 POP SdI 提交
• "pop-to-webhook" — 投递至 webhook（需要 id）
• "fatture-in-cloud" — 投递至 Fatture in Cloud

发送的 API 负载：

{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": { "...invoice fields..." },
  "integration": { "use": "sdi-via-pop", "action": "create" }
}

当 submit_to_sdi 为 false 且未提供覆盖配置时，将省略 integration（仅生成 XML）。

---

pop_create_peppol_invoice

生成 Peppol UBL 2.1 文档。可选择将其提交至 Peppol 网络。

MCP 输入：

参数	类型	必填	说明
data	对象	✅	完整发票数据。customer_type 必须为 "company" 或 "freelance"
submit_to_peppol	布尔值	—	设为 true 可提交至 Peppol 网络。需要 Basic+ 计划。默认值：false
integration	对象	—	覆盖集成配置
environment	字符串	—	目标环境

integration.use 的集成选项：

• "peppol-via-pop" 或 "peppol" — 通过 POP Peppol 提交
• "pop-to-webhook" — 投递至 webhook（需要 id）

Peppol 特有的 VAT 免税规则：

• data.nature 是 VAT 免税代码（例如 VATEX-EU-G、VATEX-EU-IC、VATEX-EU-AE 或 VATEX-EU-O 等 VATEX 代码；这些只是示例，并非完整列表）。它保留为自由字符串：POP API 会验证该值，并以通俗易懂的错误信息作出响应。
• 免税代码由用户提供。模型绝不会选择、推断（国家、vies、VAT 税率）或更改该代码；如果缺少代码，会询问用户。API 错误会显示给用户，且不会使用其他代码重试调用。
• 当代码为 VATEX-EU-IC 时，API 要求提供 data.delivery_data.country（ISO 3166-1 alpha-2 国家代码，仅限国家，绝不可填写地址）。delivery_data.date（YYYY-MM-DD）为可选字段，默认为单据日期。贷项通知单应携带与其冲销的发票相同的 delivery_data。

发送的 API 负载：

{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": { "...invoice fields...", "nature": "VATEX-EU-IC", "delivery_data": { "country": "FR" } },
  "integration": { "use": "peppol-via-pop", "action": "create" }
}

---

pop_create_pdf_invoice

生成带品牌标识的 PDF 发票。可选择将其通过电子邮件发送给最多 3 位收件人。

MCP 输入：

参数	类型	必填	说明
data	对象	✅	发票数据。必须包含用于 PDF 特定设置的 data.pdf
send_email	布尔值	—	设为 true 可通过电子邮件发送 PDF（需要 data.pdf.email_invoice 和 Basic+ 计划）。默认值：false
environment	字符串	—	目标环境

data.pdf 字段：

字段	说明
doc_type_title	单据上显示的标题（例如 "Invoice"、"Receipt"）
logo_url	公司徽标 URL（HTTPS）
head.store_info_address	页眉中的供应商地址字符串
head.billing[]	客户账单地址数组
head.shipping[]	收货地址数组（可选）
email_invoice.to	最多 3 个收件人电子邮件地址
email_invoice.from	回复地址
footer_text	自定义页脚消息
total_tax	以字符串表示的税额合计

发送的 API 负载：

{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": {
    "...invoice fields...",
    "pdf": {
      "doc_type_title": "Invoice",
      "logo_url": "https://example.com/logo.png",
      "head": { "store_info_address": "Via Roma 1, 00100 Roma IT", "billing": [] },
      "total_tax": "22.00",
      "email_invoice": { "to": ["[email protected]"] }
    }
  }
}

---

pop_create_ksef_invoice

生成波兰 KSeF FA(3) XML 发票或贷项通知单。可选择通过已配置的 KSeF 提供商集成提交。

MCP 输入：

参数	类型	必填	说明
data	object	✅	用于生成 KSeF FA(3) 的完整发票数据
integration	object	—	可选的 KSeF 提供商提交配置：{ use: "ksef" | "ksef-via-pop", action }
environment	string	—	目标环境（例如 "sandbox"）

KSeF 特定的领域规则：

• 仅限波兰 — transfer_lender.personal_data.tax_id_vat.country_id 必须为 "PL"，且 id_code 必须为 10 位 NIP
• customer_type 必须为 "company" 或 "freelance"（不接受个人客户）
• KSeF 顶层始终要求提供 nature（与 SdI/Peppol 不同，后两者仅在 VAT 为 0% 时要求提供）— 复用相同的 SdI nature 代码（N1、N2.1、N2.2、N3.1、N3.2、N4 等）来推导 KSeF 的内部财税类型
• 不使用 transmitter_data（仅适用于 SdI）
• payment_data.payment_details 仅接受 MP01、MP02/MP03、MP05、MP08 — 生成时会拒绝其他付款方式代码
• 所有套餐均可生成基础 XML；通过 integration.use: "ksef" 提交到提供商则需要 Basic+ 套餐，且供应商已在 POP 控制面板中注册为 KSeF 法律实体

发送的 API 载荷：

{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": { "...invoice fields...", "nature": "N1" },
  "integration": { "use": "ksef", "action": "create" }
}

仅在本地生成 XML（不提交到提供商）时，才会完全省略 integration。

**返回：**本地生成时返回原始 FA(3) XML（application/xml）；通过提供商集成提交时返回 JSON（包含 UUID）。

---

pop_create_zugferd_invoice

生成 ZUGFeRD/Factur-X 文档包：可视化 PDF、EN16931 CII XML，以及嵌入 XML 的混合 PDF/A-3。

MCP 输入：

参数	类型	必填	说明
data	object	✅	用于生成 ZUGFeRD/Factur-X 的完整发票数据
environment	string	—	目标环境（例如 "sandbox"）

此工具没有 integration 参数 — ZUGFeRD 仅支持本地生成，不提供提交或交付步骤。

发送的 API 载荷：

{
  "license_key": "YOUR_LICENSE_KEY",
  "user_agent": "pop-mcp",
  "user_agent_version": "1.0.0",
  "data": { "...invoice fields..." }
}

**返回：**包含生成元数据和三个 Base64 编码附件的 JSON：

{
  "success": true,
  "data": {
    "valid": true,
    "profile": "EN16931",
    "attachments": {
      "pdf": { "filename": "...", "mime": "application/pdf", "content_base64": "..." },
      "xml": { "filename": "...", "mime": "application/xml", "content_base64": "..." },
      "hybrid_pdf": { "filename": "...", "mime": "application/pdf", "content_base64": "..." }
    },
    "validation": { "...": "..." },
    "errors": [],
    "warnings": []
  }
}

---

pop_get_invoice_status

获取已提交发票的 SdI 处理状态和通知。

MCP 输入：

参数	类型	必填	说明
uuid	string (UUID)	✅	当 submit_to_sdi=true 时，由 pop_create_sdi_invoice 返回的发票 UUID
response_format	"markdown" | "json"	—	输出格式。默认值："markdown"
environment	string	—	目标环境

发送的 API 载荷：

{
  "license_key": "YOUR_LICENSE_KEY",
  "integration": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
}

SdI 通知状态： pending · accepted · rejected · delivery

SdI 处理是异步的，可能需要几分钟到几小时。如果暂未返回通知，请重试。

---

pop_get_peppol_document

通过 UUID 从 Peppol 网络中获取文档。

MCP 输入：

参数	类型	必填	说明
uuid	string (UUID)	✅	来自 pop_create_peppol_invoice 的 Peppol 文档 UUID
zone	string (2 chars)	—	Peppol 接入点所在国家的代码（例如比利时为 "BE"）。某些地区必填。
response_format	"markdown" | "json"	—	输出格式。默认值："markdown"
environment	string	—	目标环境

发送的 API 载荷：

{
  "license_key": "YOUR_LICENSE_KEY",
  "integration": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "zone": "IT" }
}

如果未提供 zone，则会从载荷中省略。

---

pop_get_sdi_document

通过 UUID 从 POP 存储中检索归档的 SdI（FatturaPA）文档。

MCP 输入：

参数	类型	必填	描述
uuid	string (UUID)	✅	SdI 文档 UUID
response_format	"markdown" | "json"	—	输出格式。默认值："markdown"
environment	string	—	目标环境

发送的 API 负载：

{
  "license_key": "YOUR_LICENSE_KEY",
  "integration": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
}

需要：Basic+ 计划，并已启用 SdI 集成。

---

pop_verify_sdi_document

在提交前验证 SdI XML 文档是否符合要求。不会提交文档。

MCP 输入：

参数	类型	必填	描述
xml_base64	string	✅	编码为 Base64 字符串的 SdI XML 文档
environment	string	—	目标环境

发送的 API 负载：

{
  "license_key": "YOUR_LICENSE_KEY",
  "skip_business_check": true,
  "integration": { "xml": "<base64-encoded-xml-string>" }
}

执行的验证检查： XML 架构符合性 · 税号格式 · VAT 号码有效性 · 必填字段是否存在 · 金额一致性

需要：Basic+ 计划、已启用 SdI 集成并已注册企业。

---

pop_preserve_document

将 SdI 文档归档至经认证的长期数字存储（conservazione sostitutiva）。意大利法律要求发票保存 10 年。

MCP 输入：

参数	类型	必填	描述
uuid	string (UUID)	✅	要归档的 SdI 文档 UUID
environment	string	—	目标环境

发送的 API 负载：

{
  "license_key": "YOUR_LICENSE_KEY",
  "integration": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
}

Important： 仅当 pop_get_invoice_status 返回状态 RC（Ricevuta di Consegna）或 MC（Mancata Consegna）时，才调用此工具。状态为 NS、EC、SE 或 DT 时，请勿调用。

需要：Basic+ 计划，并已启用 SdI 集成。

---

使用示例

生成简单的意大利发票（仅 XML）

向 AI 助手提问：

“为 Rossi SRL（增值税号 IT12345678901，米兰）开具一张金额为 1000€ + 22% VAT 的 FatturaPA 发票。我的公司是 Bianchi SRL（增值税号 IT98765432109，罗马），付款方式为银行转账至 IBAN IT60X0542811101000000123456。”

向 SdI 提交发票

“为客户 Mario Rossi（税号 RSSMRA80A01H501U，罗马）创建并向 SdI 提交一张发票 #45，内容为咨询服务，金额 500€ + 22% VAT。”

提交后检查发票状态

“UUID 为 abc123-def456-... 的 SdI 发票状态是什么？”

生成 PDF 并通过电子邮件发送

“为订单 #123 创建 PDF 发票，并通过电子邮件发送给 [email protected]。”

发送前验证 SdI 文档

“在提交前验证 UUID 为 abc123-... 的 SdI 文档是否符合要求。”

---

计划要求

功能	Free	Basic/Growth	Pro
XML 生成（本地）	✅	✅	✅
PDF 生成	✅	✅	✅
SdI 提交	❌	✅	✅
Peppol 提交	❌	✅	✅
通过电子邮件发送 PDF	❌	✅	✅
SdI 文档验证	❌	✅	✅
文档保存	❌	✅	✅

---

测试

MCP Inspector（交互式）

npm run inspector
# or
npx @modelcontextprotocol/inspector dist/cli.js

快速冒烟测试

POP_API_KEY=your_key node -e "
import('./dist/cli.js').catch(e => {
  if (e.message.includes('stdin')) process.exit(0);
  console.error(e); process.exit(1);
});
"

测试工具架构列表

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | POP_API_KEY=test node dist/cli.js

---

开发

# Run with auto-reload
npm run dev

# Build
npm run build

# Clean build artifacts
npm run clean

---

发票数据结构

用于创建发票的 data 参数遵循 FatturaPA 结构：

data
├── id                    Invoice/order ID (numeric)
├── filename              Output filename without extension (e.g. 'IT99900088876_00009')
├── type                  "invoice" | "credit_note"
├── version               "FPR12" | "FPA12"
├── sdi_type              7-char SDI code ('0000000' for private individuals)
├── customer_type         "private" | "company" | "freelance" | "pa"
├── nature                VAT exemption code (required when rate is 0%, e.g. 'N2.1', 'N6.1')
├── transmitter_data
│   ├── transmitter_id    { country_id, id_code }
│   ├── progressive       Transmission progressive ID (e.g. '00001')
│   ├── transmitter_format  "FPR12" | "FPA12"
│   ├── sdi_code          7-char code
│   ├── transmitter_contact { phone, email }
│   └── recipient_pec     PEC email (alternative to sdi_code)
├── transfer_lender       Supplier/seller
│   ├── personal_data     { tax_id_vat: { country_id, id_code, tax_regime }, company_name }
│   ├── place             { address, zip_code, city, province_id, country_id }
│   └── contact           { phone, email }
├── transferee_client     Customer/buyer
│   ├── personal_data     { tax_id_vat, tax_id_code (fiscal code for IT private), company_name }
│   └── place             { address, zip_code, city, province_id, country_id }
├── invoice_body
│   ├── general_data      { doc_type (TD01|TD04), date (YYYY-MM-DD), invoice_number, currency }
│   └── total_document_amount
├── order_items[]
│   ├── description, quantity, unit
│   ├── unit_price, total_price
│   ├── rate              VAT rate as string (e.g. '22.00')
│   ├── total_tax         VAT amount (number)
│   └── item_type         "product" | "shipping" | "fee"
├── payment_data
│   ├── terms_payment     TP01 (instalment) | TP02 (full) | TP03 (advance)
│   ├── payment_details   MP01 (Cash) | MP02 (Check) | MP05 (Bank Transfer) | MP08 (Credit Card) | ...
│   ├── payment_amount
│   ├── beneficiary       Required for MP05 (bank transfer)
│   ├── financial_institution  Required for MP05
│   └── iban              Required for MP05
├── purchase_order_data   (optional) { id, date }
├── delivery_data         (optional, Peppol) { country, date? } — country required for VATEX-EU-IC
├── connected_invoice_data[]  (required for credit notes) { id, date }
├── overrides             (optional) { language, bollo_force_apply }
└── pdf                   (only for pop_create_pdf_invoice)
    ├── doc_type_title
    ├── logo_url
    ├── head              { store_info_address, billing[], shipping[] }
    ├── total_tax
    ├── email_invoice     { to[] (max 3), from }
    └── footer_text

---

错误参考

错误代码	含义	解决方案
unauthorized_user	许可证密钥无效	检查 POP_API_KEY
insufficient_level	计划等级过低	升级 POP 计划
business_not_registered	没有企业资料	在 popapi.io 注册
integration_inactive	未启用 SdI/Peppol	在 popapi.io 激活
pop_api_email_limit	收件人超过 3 个	减至最多 3 个
pop_api_email_not_allowed	计划不支持电子邮件功能	升级至 Basic+

---

相关项目

• n8n-nodes-pop — POP 的 n8n 社区节点
• POP — 官方网站
• API 文档 — Postman 文档

---

许可证

MIT © getpopapi