Skip to main content
Glama
mcp-invoicenow-sg

mcp-invoicenow-sg

mcp-invoicenow-sg 🇸🇬

English

PyPI version Python License mcp-invoicenow-sg MCP server


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. the invoice_uuid requirement) 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. See EN16931_BASE_UNAVAILABLE_WARNING in every validate_invoice_sg result (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_sg tool: 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 xslt2 extra (pip install mcp-invoicenow-sg[xslt2]) — required for validate_invoice_sg to run. The bundled IRAS C5 stylesheet requires XSLT 2.0.

Using uvx (recommended)

uvx mcp-invoicenow-sg

Using uv

uv add mcp-invoicenow-sg

From source

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

Configuration

Environment variables

Variable

Required

Default

Description

LOG_LEVEL

No

INFO

Logging level: DEBUG, INFO, WARNING, or ERROR

EINVOICING_PEPPOL_CODELIST_DIR

No

—

Local directory containing your own copy of the OpenPeppol eDEC Code Lists, required by the list_*/check_* Peppol codelist tools (not bundled with this package; see mcp-einvoicing-core README). Participant lookup, AS4 send, and directory search work without it.

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.json

  • Project (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.json

  • Workspace (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

generate_invoice_sg

Build an SGInvoice from structured data and serialize it to UBL 2.1 XML.

validate_invoice_sg

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).

get_gst_category_codes_sg

Return the IRAS GST category codes (Annex E) accepted on Singapore invoices.

get_profile_urn_sg

Return the CustomizationID (BT-24) and ProfileID (BT-23) for a given profile (PINT_SG or BIS3).

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

peppol_lookup_participant

Check whether a business is registered on the Peppol network; returns registration status and supported document types

peppol_get_service_endpoint

Fetch the AS4 endpoint for a participant's document type

resolve_peppol_dns

DNS-only (SML) diagnostic, independent of SMP reachability

peppol_send

Transmit a UBL/CII invoice via AS4

peppol_directory_search

Search the public Peppol Directory by participant, name, country, or document type

list_participant_id_schemes, list_document_type_ids, list_process_ids, list_spis_use_case_ids

OpenPeppol eDEC codelist lookups (require 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 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.py

Vendor 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

mcp-einvoicing-core

🇧🇪 Belgium

mcp-einvoicing-be

🇧🇷 Brazil

mcp-nfe-br

🇫🇷 France

mcp-facture-electronique-fr

🇩🇪 Germany

mcp-einvoicing-de

🇮🇳 India

mcp-einvoicing-in

🇮🇹 Italy

mcp-fattura-elettronica-it

🇲🇽 Mexico

mcp-cfdi-mx

🇵🇱 Poland

mcp-ksef-pl

🇸🇬 Singapore

mcp-invoicenow-sg

🇪🇸 Spain

mcp-facturacion-electronica-es

🇦🇪 United Arab Emirates

mcp-einvoicing-ae

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 tools
check_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_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

    A3.7/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      34
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      43
      93 PyPI
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      50
      297 PyPI
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for Polish Electronic Invoicing (KSeF / FA(2)). Provides tools to validate, generate, and explore API specifications for KSeF interoperability.
      10
      263 PyPI
      3
      Apache 2.0