mcp-ksef-pl

mcp-ksef-pl 🇵🇱

English | Polski

一个 Python MCP 服务，为符合 KSeF (FA(2)) 和 Peppol BIS Billing 3.0 / EN 16931 标准的波兰电子发票提供工具。它使 AI Agent（Claude、IDE）能够生成、验证并向 Krajowy System e-Faktur (KSeF) 提交发票，还能验证波兰税务标识符（NIP 和 REGON）。

---

简介

此软件包基于 mcp-einvoicing-core，这是欧洲电子发票 MCP 服务的共享基础库。它提供 OAuth2 HTTP 客户端、令牌缓存、数据模型、日志工具和异常层级结构。

mcp-einvoicing-core 会作为依赖项自动安装，无需额外步骤。

安装

通过 PyPI（推荐）

pip install mcp-ksef-pl

也可以使用 uvx，无需预先安装：

uvx mcp-ksef-pl

从源代码安装

git clone https://github.com/cmendezs/mcp-ksef-pl.git
cd mcp-ksef-pl
uv sync --all-extras

配置（环境变量）

变量	默认值	说明
KSEF_ENVIRONMENT	test	KSeF 环境：production 或 test
KSEF_SESSION_TOKEN	—	KSeF 会话令牌（通过与 MF 进行质询-响应流程获取）
KSEF_NIP	—	提交发票的实体的 NIP
KSEF_TIMEOUT	30	HTTP 请求超时时间（秒）
KSEF_VERIFY_MF_KEY_PINNING	false	对 MF 加密证书强制执行 SPKI SHA-256 固定。即使设为 true，在当前环境的指纹填充完成前，此设置也不会生效
EINVOICING_PEPPOL_CODELIST_DIR	—	包含你自己的 OpenPeppol eDEC 代码列表副本的本地目录，Peppol 代码列表工具必需（本软件包不包含此副本；参见 mcp-einvoicing-core README）
EINVOICING_EN16931_CODELIST_DIR	—	包含你自己的 CEF “Digital Building Blocks” EN 16931 语义代码列表副本的本地目录，EN 16931 代码列表工具必需（不随软件包提供；参见 mcp-einvoicing-core README）

EUSR/TSR 报告和 MLS 工具还需要 [xslt2] 附加组件（pip install "mcp-ksef-pl[xslt2]"）以进行 Schematron 验证。

Claude Desktop 集成

将以下配置添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      }
    }
  }
}

Cursor 集成

Cursor 通过 stdio 支持 MCP 服务。将配置添加到：

• 全局（所有项目）：~/.cursor/mcp.json
• 每个项目（仅此仓库）：.cursor/mcp.json

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      }
    }
  }
}

保存更改后，重新加载 Cursor 窗口（Ctrl+Shift+P → 重新加载窗口）。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务：

• 全局：~/.kiro/settings/mcp.json
• 工作区：.kiro/settings/mcp.json

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

安全提示：与其直接输入令牌，不如使用语法 "KSEF_SESSION_TOKEN": "${KSEF_SESSION_TOKEN}"，因为 Kiro 会在启动时解析 shell 环境 变量。

可用工具

FA(3) / FA(2) 发票处理

工具	描述
generate_fa3_invoice	生成符合 KSeF 规范的 FA(3) XML 发票（通过 KSeF API v2 提交时必需）
generate_fa2_invoice	生成符合 KSeF 规范的 FA(2) XML 发票（旧版格式，仅供读取）
validate_fa3_invoice	验证 FA(3) XML：XSD 验证和 FA(3) 专属业务规则
validate_fa2_invoice	验证 FA(2) XML：XSD 验证（如果架构可用）和业务规则
parse_fa2_invoice	将 FA(2) XML 解析为结构化字典

官方 FA(2) 和 FA(3) XSD 架构随软件包一同提供（位于 src/mcp_ksef_pl/schemas/）， 并通过 importlib.resources 自动加载——无需手动下载或配置。 validate_fa2_invoice 和 validate_fa3_invoice 在所有安装中均开箱即用，可执行完整的 XSD 验证。

KSeF 生命周期

工具	描述
submit_invoice_to_ksef	向 KSeF 平台提交 FA(3) 发票，并返回参考编号
get_ksef_invoice_status	通过发票参考编号获取其处理状态
search_ksef_invoices	按日期范围和方向（卖方／买方）搜索 KSeF 中的发票

标识符验证

工具	描述
validate_polish_nip	使用校验和算法验证 NIP（10 位税务识别号）
validate_polish_regon	使用校验和算法验证 REGON（9 位或 14 位登记号）

Peppol / EN 16931

工具	描述
generate_peppol_invoice	生成符合 Peppol BIS Billing 3.0 / EN 16931 的 UBL 2.1 发票
validate_peppol_invoice	根据 CEN EN 16931 基础 Schematron 规则验证 UBL 2.1 Peppol 发票（en16931-base-only 范围——不检查 Peppol 专属扩展规则）

Peppol 网络工具

Peppol 参与方查询、服务端点查询、仅 DNS 诊断、AS4 发送、Peppol Directory 搜索以及 OpenPeppol eDEC 代码表工具由共享核心 Peppol 工具插件（mcp_einvoicing_core.peppol.tools.register_peppol_tools）提供，并在 server.py 中挂载，使用波兰专属标识符适配器：裸 NIP（例如 1234563218）会规范化为 9945:<digits> Peppol 方案（PL:VAT，依据 OpenPeppol eDEC 参与方标识符方案代码表）；已包含方案的标识符（例如 9945:1234563218）则保持不变。可使用这些工具，在调用 generate_peppol_invoice 前检查 PEF（波兰用于公共采购 B2G 开票的 Peppol 接入点）注册状态。

自 mcp-einvoicing-core v1.20.0 起，peppol_send 会使用真实的 wsse:Security 签名对出站消息进行签名（此前会计算签名后将其丢弃——参见 CHANGELOG.md v0.8.0）。

工具	描述
peppol_lookup_participant	检查企业是否已在 Peppol 网络注册；返回注册状态和支持的文档类型
peppol_get_service_endpoint	获取参与方对应文档类型的 AS4 端点
resolve_peppol_dns	仅 DNS（SML）诊断，不受 SMP 可达性影响
peppol_send	通过 AS4 传输 UBL/CII 发票
peppol_directory_search	按参与方、名称、国家或文档类型搜索公开的 Peppol Directory
list_participant_id_schemes、list_document_type_ids、list_process_ids、list_spis_use_case_ids	OpenPeppol eDEC 代码表查询（需要 EINVOICING_PEPPOL_CODELIST_DIR）
check_document_type_id_in_codelist、check_process_id_in_codelist、check_participant_id_scheme_in_codelist、get_peppol_codelist_version	OpenPeppol eDEC 代码表检查和版本报告

有关这些工具完整的参数说明，请参阅 mcp-einvoicing-core README。

Peppol 报告和状态工具

在 v0.8.0 中通过三个可选的核心插件添加，并在 server.py 中无条件挂载。如果缺少相应扩展或数据目录，这些工具会在调用时（而非注册时）明确报错。

工具	插件	描述
validate_eusr_report	register_peppol_reporting_tools	验证最终用户统计报告（先进行 XSD 验证，再进行 Schematron 验证）。需要 [xslt2] 扩展。
validate_tsr_report	register_peppol_reporting_tools	验证交易统计报告（先进行 XSD 验证，再进行 Schematron 验证）。需要 [xslt2] 扩展。
validate_mls_message	register_peppol_mls_tools	验证消息级状态文档（UBL ApplicationResponse-2 子集）。需要 [xslt2] 扩展。
build_mls_message	register_peppol_mls_tools	构建文档级 MLS 响应。需要 [xslt2] 扩展。
13 对 list_*/check_* 工具，以及 get_en16931_codelist_version	register_en16931_codelist_tools	EN 16931 语义代码列表查询/检查（单位、VAT 类别等）。需要设置 EINVOICING_EN16931_CODELIST_DIR。

有关这些工具的完整参数说明，请参阅 mcp-einvoicing-core README。

KSeF 身份验证

KSeF API v2 通过多步质询/兑换流程颁发 AccessToken。此 MCP 服务接受已获取的令牌，无法自动完成签名步骤（该步骤需要合格的电子签名）。

分步流程

1. 账户设置。 在 KSeF 门户注册：https://ksef.mf.gov.pl/。选择目标环境（测试或生产）。测试环境地址为 https://ksef-test.mf.gov.pl/。

2. 请求质询。 调用 KSeF API，获取质询 XML 信封：

   curl -s https://ksef-test.mf.gov.pl/auth/challenge \
     -H "Accept: application/json" \
     -d '{"contextIdentifier": {"type": "onip", "identifier": "YOUR_NIP"}}' \
     -H "Content-Type: application/json"
   

   响应包含一个 challenge 字符串和一个 timestamp。

3. 签署质询。 构建包含质询的 <InitSessionTokenRequest> XML 信封，然后使用合格的电子签名进行签署。可接受的签署工具：

   • 合格电子签名提供商：KIR (Szafir)、Certum、Sigillum
   • podpis.gov.pl（政府签名门户）
   • Profil Zaufany（可信档案）：https://www.podatki.gov.pl/ksef/

   使用 PKCS#12 证书和 xmlsec1 的示例：

   # Build the challenge XML (template at specs/przyklad-wyzwania.xml)
   xmlsec1 --sign --pkcs12 your-cert.p12 --pwd "password" \
     --output signed-challenge.xml challenge-template.xml
   

4. 提交已签署的质询。 POST 已签署的 XML，以获取 authOperation 引用：

   curl -s https://ksef-test.mf.gov.pl/auth/xades-signature \
     -H "Content-Type: application/octet-stream" \
     --data-binary @signed-challenge.xml
   

5. 兑换 AccessToken。 将已验证身份的操作兑换为 AccessToken：

   curl -s https://ksef-test.mf.gov.pl/auth/token/redeem \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <referenceNumber-or-authOperation-token-from-step-4>"
   

   响应包含 accessToken.token 和 accessToken.context.referenceNumber。

6. 设置令牌。 为此 MCP 服务导出令牌：

   export KSEF_SESSION_TOKEN="<the AccessToken from step 5>"
   

   根据 MF 文档，令牌自颁发起约 2 小时内有效。过期后，请重复步骤 2-5。

参考资料

• KSeF 技术文档：https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/
• 身份验证规范（CIRFMF）：https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md
• 交互式会话规范（CIRFMF）：https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md
• FA(3) 迁移公告：specs/ksef-v2-fa3-migration-announcement-20250630.pdf

架构

此服务充当 AI Agent 与 KSeF 平台及 Peppol 网络之间的智能通信接口：

[ ERP System / Application ] <--> [ MCP Server ] <--> [ KSeF (MF) / Peppol Network ]
          ^                           |
          |                           v
   [ AI Agent (Claude) ] <--- (FA(2) / EN 16931)

厂商中立性

此服务自行实现标准：在本地构建、验证并签署文档。它不是商业开票平台的客户端，您的签名密钥和凭据也绝不会离开您自己的基础设施。

发票使用您自己的身份验证令牌直接发送至 KSeF，无需中间方。

测试

# Run unit tests
uv run pytest tests/ -v

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 了解指南。

其他电子发票 MCP 服务

国家/地区	服务
🌍 全球	mcp-einvoicing-core
🇧🇪 比利时	mcp-einvoicing-be
🇧🇷 巴西	mcp-nfe-br
🇫🇷 法国	mcp-facture-electronique-fr
🇩🇪 德国	mcp-einvoicing-de
🇮🇳 印度	mcp-einvoicing-in
🇮🇹 意大利	mcp-fattura-elettronica-it
🇲🇽 墨西哥	mcp-cfdi-mx
🇵🇱 波兰	mcp-ksef-pl
🇸🇬 新加坡	mcp-invoicenow-sg
🇪🇸 西班牙	mcp-facturacion-electronica-es
🇦🇪 阿联酋	mcp-einvoicing-ae

许可证

本项目根据 Apache 2.0 许可证发布。 详情请参阅 LICENSE 文件。完整的版本历史记录请参阅 CHANGELOG.md。