mcp-invoicenow-sg

mcp-invoicenow-sg 🇸🇬

English

---

简介

mcp-invoicenow-sg 是一个用于新加坡电子发票的 MCP（Model Context Protocol） 服务，通过由 IMDA 运营的全国电子发票平台 InvoiceNow 处理发票。它可构建并验证 PINT-SG v1.4.1 和 SG Peppol BIS Billing 3.0 的发送发票（即原始开具的发票，而非接收／采购端发票）。它属于面向特定国家的 mcp-einvoicing-* 服务系列，所有服务均基于 mcp-einvoicing-core 构建；该核心库提供共享验证引擎、EN 16931 抽象和 Peppol 网络工具。

支持的标准

• PINT-SG v1.4.1（urn:peppol:pint:billing-1@sg-1）——推荐新发送方使用的配置文件。
• SG Peppol BIS Billing 3.0——旧版配置文件，早于 PINT 计划。
• 两者均符合 EN 16931；发票模型扩展了 mcp_einvoicing_core.en16931.EN16931Invoice。
• 验证会运行 IRAS 自有的 C5 接受层（non_peppol_doc_validation）——这是政府官方产物，例如会标记缺少买方／卖方 UEN 的情况。截至 v0.2.0，尚未检查 PINT-SG 自有的司法辖区 Schematron 规则（例如 invoice_uuid 要求）——详见下文“尚不支持”。

尚不支持（详见 specs/README.md）：

• CEN EN16931 基础规则和 PINT-SG 司法辖区 Schematron 验证。 v0.1.0 包含一份自行编译的 OpenPeppol PINT-SG 司法辖区 Schematron 衍生版本，但未确认其再分发权；该文件已于 v0.2.0（2026-08-28）移除。共享且许可合规的核心 CEN EN16931 基础验证器已接入，但尚未在 SG 启用——SGInvoice 的 IRAS GST 类别代码尚无来源明确的映射表，可映射至该验证器所需的 UNCL5305 代码列表。每个 validate_invoice_sg 结果中的 EN16931_BASE_UNAVAILABLE_WARNING（追踪编号为 [CORE-EN16931-BASE-SG-CROSSWALK-1]）说明了启用该功能所需的条件。
• Peppol 订单消息系列（Order、OrderResponse 等）以及 IMDA 的新加坡专属订单余额。
• UBL 2.1 XSD 结构验证。 已在本包自己的测试套件中通过真实 UBL 2.1 架构证明其正确性（仅用于测试的样例文件，不随 wheel 发布），但尚未接入 validate_invoice_sg 工具：所需的 OASIS UBL 2.1 架构文件尚未获得本地确认的再分发许可。
• IRAS 自有的发票数据提交 API（专指“第五角”C5 副本，与通用 Peppol AS4 传输不同；下文的 Peppol 工具支持后者）——没有公开文档说明 IMDA 认可的接入点实际使用的 API 基础 URL 或身份验证流程。
• SG Peppol BIS Billing 3.0 Schematron 验证——此配置文件未附带规则集。
• 接收／采购端发票模型（LocalTaxInvoice、TX2_Annex Annex B Type 1B）。

安装

要求

• Python ≥ 3.11
• mcp-einvoicing-core（作为依赖自动安装）
• 可选：xslt2 扩展（pip install mcp-invoicenow-sg[xslt2]）——运行 validate_invoice_sg 所必需。内置的 IRAS C5 样式表要求 XSLT 2.0。

使用 uvx（推荐）

uvx mcp-invoicenow-sg

使用 uv

uv add mcp-invoicenow-sg

从源代码安装

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

配置

环境变量

变量	必需	默认值	描述
LOG_LEVEL	否	INFO	日志级别：DEBUG、INFO、WARNING 或 ERROR
EINVOICING_PEPPOL_CODELIST_DIR	否	—	包含你自行获取的 OpenPeppol eDEC Code Lists 副本的本地目录；list_*/check_* Peppol 代码列表工具需要此目录（本软件包不包含该副本；请参阅 mcp-einvoicing-core README）。参与方查询、AS4 发送和目录搜索无需此目录即可运行。

运行此服务无需凭据。

Claude Desktop 集成

要将此服务与 Claude 配合使用，请将以下配置添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "invoicenow-sg": {
      "command": "uvx",
      "args": ["mcp-invoicenow-sg"]
    }
  }
}

Cursor 集成

Cursor 支持通过 stdio 使用 MCP 服务。请在以下位置添加配置：

• 全局（所有项目）：~/.cursor/mcp.json
• 项目（仅此代码库）：.cursor/mcp.json

{
  "mcpServers": {
    "invoicenow-sg": {
      "command": "uvx",
      "args": ["mcp-invoicenow-sg"]
    }
  }
}

重新加载 Cursor 窗口（按 Ctrl+Shift+P，然后选择 Reload Window）以应用更改。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务。提供以下两个级别：

• 全局（所有项目）：~/.kiro/settings/mcp.json
• 工作区（仅此代码库）：.kiro/settings/mcp.json

{
  "mcpServers": {
    "invoicenow-sg": {
      "command": "uvx",
      "args": ["mcp-invoicenow-sg"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

保存后会自动重新加载文件。你也可以通过命令面板打开配置（按 Cmd+Shift+P / Ctrl+Shift+P），然后选择 MCP。

可用工具

工具	描述
generate_invoice_sg	根据结构化数据构建 SGInvoice，并将其序列化为 UBL 2.1 XML。
validate_invoice_sg	根据 IRAS 的 C5 验收层验证 UBL 2.1 发票（不检查 CEN EN16931 基础规范、PINT-SG 司法辖区 Schematron、SG BIS 3.0 和 UBL 2.1 XSD 结构验证；请参阅上文“尚不支持”）。
get_gst_category_codes_sg	返回新加坡发票所接受的 IRAS GST 类别代码（Annex E）。
get_profile_urn_sg	返回指定配置文件（PINT_SG 或 BIS3）的 CustomizationID（BT-24）和 ProfileID（BT-23）。

**推荐工作流：**先使用 get_profile_urn_sg 选取配置文件对，然后在发票数据中使用该配置文件对调用 generate_invoice_sg，最后对结果调用 validate_invoice_sg。

Peppol 工具

通用 Peppol 网络工具（参与方查询、AS4 发送、目录搜索、eDEC 代码列表）也已注册，来源为 mcp_einvoicing_core.peppol.tools；裸新加坡 UEN 会规范化为 scheme 0195 参与方 ID：

工具	描述
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 代码列表检查和版本报告

peppol_send 是通用的 Peppol AS4 传输工具，可将内容发送到接收方的 Access Point；它不同于向 IRAS 自有的 C5 端点提交内容，此功能仍不受支持（请参阅上文“尚不支持”）。

docs/TOOLS.md 中的工具参考文档由运行中的服务生成：

uv run python scripts/gen_tool_reference.py

供应商中立性

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

InvoiceNow 需要 Peppol 接入点，但任何获认证的接入点都支持相同的 AS4 配置文件，因此更换供应商只需修改配置，无需修改代码。

贡献

开发环境设置、测试和 lint 命令，以及拉取请求检查清单，请参阅 CONTRIBUTING.md。安全问题请按照 SECURITY.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。