mcp-einvoicing-core

English | Francais | Deutsch | Italiano | Espanol | Portugues (Brasil) | العربية

Topics: mcp mcp-server e-invoicing electronic-invoicing python fastmcp peppol en16931 ubl fatturapa xp-z12-013 nfe xml base-library

Base package for electronic invoicing MCP servers.

Provides shared Pydantic models, EN 16931 invoice tree, UBL/CII wire format serializers, an OAuth2 HTTP client, Peppol SMP lookup, digital signature primitives, and a compliance audit framework so country-specific packages share a common foundation without duplicating code.

What this package provides

Country packages

Installation

pip install mcp-einvoicing-core

For the compliance audit framework (used by country package CI):

pip install mcp-einvoicing-core[audit]

For XSLT 2.0/3.0 Schematron validation (SaxonSchematronValidator — needed for Schematron rule sets using XPath 2.0+ constructs, e.g. FNFE-MPE Factur-X 1.08 / ZUGFeRD):

pip install mcp-einvoicing-core[xslt2]

Configuration

Architecture

Country packages subclass the core abstractions and register their tools on a shared or standalone MCP server:

mcp-einvoicing-core
  ├── EN16931Invoice / InvoiceDocument  ← canonical invoice models
  ├── EN16931CreditNote                 ← credit note (type codes 381/383/384/385)
  ├── EN16931UBL/CII Serializer/Parser  ← wire format round-trip
  ├── convert_wire_format               ← CII ↔ UBL conversion
  ├── BaseDocumentGenerator/Validator/Parser/LifecycleManager
  ├── BaseEInvoicingClient              ← async HTTP (OAuth2/mTLS/bearer/API key/JWS)
  ├── PeppolSMPClient                   ← participant lookup via SMP/SML
  ├── PeppolTransmitter                 ← AS4 outbound transmission
  ├── BaseDocumentSigner                ← XAdES-EPES / XMLDSig
  ├── BaseEnvironmentEndpoints          ← sandbox/production URL routing
  ├── RoutingIdentifier                 ← country-specific routing ID validation
  ├── EInvoicingMCPServer               ← plugin registry wrapping FastMCP
  └── Audit framework                   ← per-package compliance checks

Vendor neutrality

Every server in this family implements the standard itself. It builds, validates and signs the document locally, and the signing keys stay in your infrastructure. None of these packages is a client for a commercial invoicing platform, and no vendor account is needed to run one.

What differs between countries is the last mile: who, if anyone, must stand between you and the tax authority. mcp-einvoicing-core supports all three arrangements, and each country package implements exactly the one its jurisdiction uses:

• Direct to the authority. No intermediary is legally required; the package talks to the government endpoint with your own accreditation. (Italy, Poland, Brazil, Spain)
• Substitutable intermediary. An intermediary is required, but its API is standardized, so changing provider is a configuration change, not a code change. (France's PDP under XP Z12-013; Peppol access points for Belgium, Singapore, the UAE)
• Adapter-per-vendor intermediary. An intermediary is required and each vendor's API differs. The document and the keys still stay yours; only the transport adapter is vendor-specific. (Mexico's PAC, India's GSP)

In all three, the compliance logic and the private keys stay with you.

Plugin registration pattern

Country packages register their tools on a shared or standalone FastMCP instance:

# Standalone
from fastmcp import FastMCP
mcp = FastMCP(name="mcp-fattura-elettronica-it", instructions="...")
register_header_tools(mcp)
register_body_tools(mcp)
register_global_tools(mcp)

# Multi-country (optional EInvoicingMCPServer)
from mcp_einvoicing_core import EInvoicingMCPServer
server = EInvoicingMCPServer(name="mcp-einvoicing-eu", instructions="...")
server.register_plugin(register_header_tools, "it-header")
server.register_plugin(register_flow_tools, "fr-flow")
server.run()

Core also ships its own mountable Peppol tool plugin so country packages stop reimplementing SMP lookup and AS4 send. Supply a national identifier adapter (a small function that normalizes a bare national number, e.g. a VAT number, into a Peppol "<scheme>:<value>" participant ID):

from mcp_einvoicing_core.peppol.tools import register_peppol_tools

def be_id_adapter(identifier: str) -> str:
    if ":" in identifier:
        return identifier
    return f"0208:{normalize_vat_be(identifier)[2:]}"  # KBO/BCE scheme

server.register_plugin(
    lambda m: register_peppol_tools(m, id_adapter=be_id_adapter), "peppol"
)

This registers peppol_lookup_participant, peppol_get_service_endpoint, resolve_peppol_dns, peppol_send, peppol_directory_search, and 8 OpenPeppol eDEC code list tools (see Configuration above for EINVOICING_PEPPOL_CODELIST_DIR, required for the code list tools). Separate mountable plugins cover the EN 16931 semantic code lists (en16931_codelist_tools.register_en16931_codelist_tools), Peppol reporting (peppol.reporting_tools.register_peppol_reporting_tools), and MLS (peppol.mls_tools.register_peppol_mls_tools).

Claude Desktop / Cursor / Kiro compatibility

Existing configurations for country packages require no changes: tool names, signatures, environment variables, and entry points (server:main) are fully preserved.

License

Apache 2.0 -- see LICENSE.