mcp-invoicenow-sg
An MCP server for Singapore e-invoicing on InvoiceNow: it builds, validates, and transmits PINT-SG v1.4.1 / SG Peppol BIS Billing 3.0 sent invoices, plus generic Peppol network utilities.
Generate invoices —
generate_invoice_sgbuilds anSGInvoicefrom structured data and serializes it to UBL 2.1 XML, returning the XML plus the applied CustomizationID/ProfileID.Pick a profile —
get_profile_urn_sgreturns the matched CustomizationID (BT-24) / ProfileID (BT-23) pair forPINT_SG(recommended) orBIS3(legacy).Validate invoices —
validate_invoice_sgruns IRAS's own C5 acceptance layer (e.g. flags a missing buyer/seller UEN); needs the optionalxslt2extra, else returnslevel="unavailable". CEN EN 16931 base, PINT-SG jurisdiction Schematron, SG BIS 3.0, and UBL 2.1 XSD checks are not performed.Look up GST codes —
get_gst_category_codes_sgreturns IRAS Annex E GST category codes (supply/output side).Peppol participant lookup — check Peppol registration and supported document types, fetch a participant's AS4 endpoint, or run a DNS-only SML diagnostic (
peppol_lookup_participant,peppol_get_service_endpoint,resolve_peppol_dns).Send over Peppol AS4 —
peppol_sendtransmits a base64 UBL/CII invoice to a recipient's Access Point using your own signing certificate and key (generic AS4 transport, not IRAS C5 submission).Search the Peppol Directory —
peppol_directory_searchby query, name, country, participant ID, or document type.Browse/verify OpenPeppol eDEC codelists —
list_*andcheck_*tools for participant ID schemes, document type IDs, process IDs, and SPIS use cases, plusget_peppol_codelist_version; these requireEINVOICING_PEPPOL_CODELIST_DIRto point at your own local codelist copy.Zero credentials to run — no API keys needed; signing keys and credentials stay in your own infrastructure.
Known gaps — Peppol Ordering messages, IRAS's own Invoice Data Submission (C5) API, SG BIS 3.0 Schematron, and the received/purchase-side invoice model are unsupported.
mcp-invoicenow-sg 🇸🇬
Introduction
mcp-invoicenow-sg is an MCP (Model Context Protocol) server
for Singapore electronic invoicing over InvoiceNow, the national e-invoicing platform
operated by IMDA. It builds and validates PINT-SG v1.4.1 and SG Peppol BIS Billing 3.0 sent
invoices (originally-issued invoices, not the received/purchase side). It is part of the
mcp-einvoicing-* family of country-specific servers, all built on
mcp-einvoicing-core, which provides the
shared validation engine, EN 16931 abstractions, and Peppol network utilities.
Related MCP server: mcp-fattura-elettronica-it
Supported standards
PINT-SG v1.4.1 (
urn:peppol:pint:billing-1@sg-1) — the recommended profile for new senders.SG Peppol BIS Billing 3.0 — legacy profile, predates the PINT programme.
Both are EN 16931-conformant; the invoice model extends
mcp_einvoicing_core.en16931.EN16931Invoice.Validation runs IRAS's own C5 acceptance layer (
non_peppol_doc_validation) — a first-party government artifact, e.g. it flags a missing buyer/seller UEN. As of v0.2.0, PINT-SG's own jurisdiction Schematron rules (e.g. theinvoice_uuidrequirement) are not checked — see "Not yet supported" below.
Not yet supported (see specs/README.md for full detail):
CEN EN16931 base and PINT-SG jurisdiction Schematron validation. v0.1.0 bundled a self-compiled derivative of OpenPeppol's PINT-SG jurisdiction Schematron with no confirmed redistribution rights; it was removed in v0.2.0 (2026-08-28). The shared, properly-licensed core CEN EN16931 base validator is wired but not yet activated for SG —
SGInvoice's IRAS GST category codes have no sourced crosswalk to the UNCL5305 code list that validator requires. SeeEN16931_BASE_UNAVAILABLE_WARNINGin everyvalidate_invoice_sgresult (tracked as[CORE-EN16931-BASE-SG-CROSSWALK-1]) for what would unblock it.The Peppol Ordering message family (
Order,OrderResponse, etc.) and IMDA's SG-specific Order Balance.UBL 2.1 XSD structural validation. Proven correct against a real UBL 2.1 schema in this package's own test suite (a test-only fixture, not shipped in the wheel), but not wired into the
validate_invoice_sgtool: the OASIS UBL 2.1 schema files needed carry no locally-confirmed redistribution grant.IRAS's own Invoice Data Submission API (the 5th-corner "C5" copy specifically, as distinct from generic Peppol AS4 transport, which the Peppol tools below do support) — no publicly available document states an IMDA-accredited Access Point's actual API base URL or authentication flow.
SG Peppol BIS Billing 3.0 Schematron validation — no rule set is bundled for this profile.
The received/purchase-side invoice model (
LocalTaxInvoice, TX2_Annex Annex B Type 1B).
Installation
Requirements
Python ≥ 3.11
mcp-einvoicing-core(installed automatically as a dependency)Optional: the
xslt2extra (pip install mcp-invoicenow-sg[xslt2]) — required forvalidate_invoice_sgto run. The bundled IRAS C5 stylesheet requires XSLT 2.0.
Using uvx (recommended)
uvx mcp-invoicenow-sgUsing uv
uv add mcp-invoicenow-sgFrom source
git clone https://github.com/cmendezs/mcp-invoicenow-sg.git
cd mcp-invoicenow-sg
uv sync --all-extrasConfiguration
Environment variables
Variable | Required | Default | Description |
| No |
| Logging level: |
| No | — | Local directory containing your own copy of the OpenPeppol eDEC Code Lists, required by the |
This server needs no credentials to run.
Claude Desktop integration
To use this server with Claude, add this configuration to your claude_desktop_config.json file:
{
"mcpServers": {
"invoicenow-sg": {
"command": "uvx",
"args": ["mcp-invoicenow-sg"]
}
}
}Cursor integration
Cursor supports MCP servers via stdio. Add the configuration in:
Global (all projects):
~/.cursor/mcp.jsonProject (this repository only):
.cursor/mcp.json
{
"mcpServers": {
"invoicenow-sg": {
"command": "uvx",
"args": ["mcp-invoicenow-sg"]
}
}
}Reload the Cursor window (Ctrl+Shift+P then Reload Window) to apply the changes.
Kiro integration
Kiro supports MCP servers via its dedicated configuration file. Two levels are available:
Global (all projects):
~/.kiro/settings/mcp.jsonWorkspace (this repository only):
.kiro/settings/mcp.json
{
"mcpServers": {
"invoicenow-sg": {
"command": "uvx",
"args": ["mcp-invoicenow-sg"],
"disabled": false,
"autoApprove": []
}
}
}The file is automatically reloaded on save. You can also open the config via the command palette (Cmd+Shift+P / Ctrl+Shift+P) then MCP.
Available tools
Tool | Description |
| Build an |
| Validate a UBL 2.1 invoice against IRAS's C5 acceptance layer (CEN EN16931 base, PINT-SG jurisdiction Schematron, SG BIS 3.0, and UBL 2.1 XSD structural validation are not checked — see "Not yet supported" above). |
| Return the IRAS GST category codes (Annex E) accepted on Singapore invoices. |
| Return the CustomizationID (BT-24) and ProfileID (BT-23) for a given profile ( |
Recommended workflow: get_profile_urn_sg to pick the profile pair, then
generate_invoice_sg with that pair in the invoice data, then validate_invoice_sg on the
result.
Peppol tools
Generic Peppol network tools (participant lookup, AS4 send, directory search, eDEC codelists)
are also registered, from mcp_einvoicing_core.peppol.tools, with bare Singapore UENs
normalized to scheme 0195 participant IDs:
Tool | Description |
| Check whether a business is registered on the Peppol network; returns registration status and supported document types |
| Fetch the AS4 endpoint for a participant's document type |
| DNS-only (SML) diagnostic, independent of SMP reachability |
| Transmit a UBL/CII invoice via AS4 |
| Search the public Peppol Directory by participant, name, country, or document type |
| OpenPeppol eDEC codelist lookups (require |
| OpenPeppol eDEC codelist checks and version reporting |
peppol_send is generic Peppol AS4 transport to the recipient's Access Point — it is not the
same as submission to IRAS's own C5 corner, which stays unsupported (see "Not yet supported"
above).
The tool reference in docs/TOOLS.md is generated from the running server:
uv run python scripts/gen_tool_reference.pyVendor neutrality
This server implements the standard itself: it builds, validates, and signs the document locally. It is not a client for a commercial invoicing platform, and your signing keys and credentials never leave your own infrastructure.
A Peppol access point is required for InvoiceNow, but any accredited access point speaks the same AS4 profile, so switching providers is a configuration change, not a code change.
Contributing
See CONTRIBUTING.md for development setup, the test and lint commands, and the pull request checklist. Security issues follow the private disclosure process in SECURITY.md.
Other e-invoicing MCP servers
Country | Server |
🌍 Global | |
🇧🇪 Belgium | |
🇧🇷 Brazil | |
🇫🇷 France | |
🇩🇪 Germany | |
🇮🇳 India | |
🇮🇹 Italy | |
🇲🇽 Mexico | |
🇵🇱 Poland | |
🇸🇬 Singapore | |
🇪🇸 Spain | |
🇦🇪 United Arab Emirates |
License
This project is licensed under the Apache 2.0 license — see LICENSE for details. For the full version history, see CHANGELOG.md.
Available Tools
17 toolscheck_document_type_id_in_codelistB
Check whether a (scheme, value) pair is a recognized Peppol document type identifier.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Searches all entries regardless of state, so a historical (deprecated
or removed) document type is still reported as found.
Inputs: value (required), scheme (required). Returns: object
check_participant_id_scheme_in_codelistA
Check whether a 4-digit ISO 6523 ICD code (e.g. "0208") is a recognized Peppol scheme.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: icd (required). Returns: object
check_process_id_in_codelistB
Check whether a (scheme, value) pair is a recognized Peppol process identifier.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: value (required), scheme (required). Returns: object
generate_invoice_sgA
Build an SGInvoice from structured data and serialize it to UBL 2.1 XML.
invoice_data['profile'] (CustomizationID) and invoice_data['business_process']
(ProfileID) select PINT-SG or SG Peppol BIS Billing 3.0, and must be a
matched pair (TX2_Annex Annex B) — use get_profile_urn_sg to look up
both values together rather than setting them independently.
Returns the UBL XML (as a string) plus the customization_id/profile_id
that were applied. Does not validate against Schematron — call
validate_invoice_sg on the returned XML for that.
Inputs: invoice_data (required). Returns: object
get_gst_category_codes_sgA
Return the IRAS GST category codes accepted on Singapore invoices.
Source: IRAS e-Tax Guide Annex E (supply/output-tax side only — the
purchase-side codes are out of scope for sent invoices). rate is
null for categories with no fixed rate ("NA" in the source table).
Inputs: no named parameters. Returns: object
get_peppol_codelist_versionA
Report the OpenPeppol eDEC code list release version(s) currently configured locally.
Inputs: no named parameters. Returns: object
get_profile_urn_sgA
Return the CustomizationID (BT-24) and ProfileID (BT-23) for a Singapore profile.
CustomizationID comes from mcp_einvoicing_core.profile_registry (registered at import time in models/invoice.py); ProfileID is a shared Peppol process identifier, not per-country, so it is returned from a local constant rather than the registry.
PINT_SG is the recommended profile for new senders — SG Peppol BIS Billing 3.0 (BIS3) predates the PINT programme and is positioned as legacy (per the package's own compliance reference, "Supported wire formats and profile URNs" — user-supplied guidance, not independently verified against an IRAS/IMDA notice). Not enforced as a hard default here; callers choose explicitly.
Inputs: profile (required). Returns: object
list_document_type_idsA
List Peppol document type identifiers from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: active_only. Returns: object
list_participant_id_schemesA
List Peppol participant identifier (ICD) schemes from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR to point at a local copy of
the eDEC "Participant Identifier Schemes" GeneriCode export (not
bundled with this package, no confirmed redistribution rights, see
mcp_einvoicing_core.peppol.codelists module docstring).
Inputs: active_only. Returns: object
list_process_idsA
List Peppol process identifiers from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: active_only. Returns: object
list_spis_use_case_idsA
List Peppol SPIS use case identifiers from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: active_only. Returns: object
peppol_directory_searchA
Search the Peppol Directory for registered participants.
Public, unauthenticated search (no relation to SMP lookup). At least one of q/participant/name/country/doctype must be supplied.
Inputs: q, name, country, doctype, +4 more. Returns: object
peppol_get_service_endpointA
Fetch the AS4 endpoint for a Peppol participant's document type.
Resolves the SMP hostname via DNS, then fetches service metadata for
document_type_id. If the SMP returns a redirect, the result's
redirect_url is set and endpoint_url is None; callers must not
follow more than one redirect hop (SMP 1.4.0 §3.2).
Inputs: identifier (required), environment, document_type_id. Returns: object
peppol_lookup_participantA
Check whether a business is registered on the Peppol network.
Performs a DNS-over-HTTPS U-NAPTR lookup followed by an SMP service-group request to determine registration status and the list of supported document type identifiers.
Inputs: identifier (required), environment. Returns: object
peppol_sendA
Send a UBL/CII invoice to a Peppol participant via AS4.
Looks up the recipient's AS4 endpoint (SMP), builds the ebMS3/AS4 envelope, and transmits it using the supplied signing credentials.
Inputs: sender_id (required), certificate_path (required), private_key_path (required), invoice_xml_base64 (required), +4 more. Returns: object
resolve_peppol_dnsA
Resolve the SMP hostname for a Peppol participant via DNS only.
Performs the raw U-NAPTR (SML) lookup without fetching the SMP service group, useful for diagnosing whether a participant is registered in the SML independently of SMP reachability.
Inputs: identifier (required), environment. Returns: object
validate_invoice_sgA
Validate a UBL 2.1 XML invoice against IRAS's C5 acceptance-layer Schematron.
Runs IRAS's own C5 acceptance layer (checks documents that IRAS
itself would still reject, e.g. a missing buyer/seller UEN). The CEN
EN16931 base ruleset, PINT-SG's own jurisdiction overlay, and SG
Peppol BIS Billing 3.0 are NOT checked — see scope and the
EN16931-BASE-UNAVAILABLE warning in the result, and
validators/schematron.py's module docstring for why (SGInvoice's GST
category codes have no sourced crosswalk to the UNCL5305 code list
the base ruleset requires; tracked as
[CORE-EN16931-BASE-SG-CROSSWALK-1]).
Requires the optional xslt2 extra (pip install mcp-invoicenow-sg[xslt2]) — the bundled stylesheet needs XSLT 2.0.
If missing, returns level="unavailable".
Inputs: xml_content (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have clearly distinct purposes, and the descriptions carefully delineate the participant-lookup family (peppol_lookup_participant vs resolve_peppol_dns vs peppol_get_service_endpoint vs peppol_directory_search). The codelist check_* vs list_* pairs are also cleanly separated. The only mild residual overlap is the cluster of registration/SMP lookups, but prose disambiguates them.
Predominantly verb_noun (generate_invoice_sg, validate_invoice_sg, list_document_type_ids, check_process_id_in_codelist), which is readable. However the peppol_ prefix is applied inconsistently (peppol_send, peppol_get_service_endpoint, peppol_lookup_participant vs list_document_type_ids, check_process_id_in_codelist with no prefix), and the _sg suffix on some tools is uneven.
17 tools is slightly heavy but each earns its place across distinct concerns: codelist listing plus per-codelist checks, profile/GST metadata, generation, validation, and the Peppol transport chain. The four list_* codelist tools are individually justified by different identifier domains. It sits near the top of the reasonable band rather than being bloated.
The generate-validate-send Peppol pipeline is covered end to end, with participant lookup, endpoint resolution, codelists, GST codes, and profile URNs. The explicit absence of EN16931 base / PINT-SG overlay validation (documented as CORE-EN16931-BASE-SG-CROSSWALK-1) and no inbound/receive path are real but acknowledged gaps.
Maintenance
Related MCP Connectors
MCP server for Codat — companies, connections, invoices, bills and financial statements.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Related MCP Servers
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for French Electronic Invoicing (NF XP Z12-013). Provide tools to validate, generate, and explore API specifications for PDP/OD interoperability.341Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Italian Electronic Invoicing (FatturaPA / SDI). Provide tools to validate, generate, and explore API specifications for Sistema di Interscambio (SDI) interoperability.4393 PyPI2Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Belgian Electronic Invoicing (Peppol BIS 3.0 / PINT-BE / Mercurius). Provides tools to validate, generate, and transform UBL 2.1 e-invoices, and look up BCE/KBO enterprise data and Peppol participants.50297 PyPIApache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Polish Electronic Invoicing (KSeF / FA(2)). Provides tools to validate, generate, and explore API specifications for KSeF interoperability.10263 PyPI3Apache 2.0