e-invoice-mcp 0.1.0

MCP Server for Fintom8 E-Invoicing services (Conversion, Validation, Correction)

Fintom8 E-Invoicing Agent (MCP)

The official Model Context Protocol (MCP) server for Fintom8.

This server acts as an intelligent bridge to AI agentic Fintom8 E-Invoice Platform. It enables autonomous agents to validate, audit, and correct e-invoices against the latest European standards (EN16931) and Peppol regulations.

General Functionalities Provided Over MCP:

• Convert Peppol UBL E-Invoice from PDF
• Validate Peppol UBL E-Invoice
• Correct Peppol UBL Invoice

Other formats and functionalities can be requested.

🚀 Features

• Autonomous Validation: Agents can send XML content and receive detailed compliance reports.
• Peppol 3.0.20 Support: Checks against the newest rules, including EAS code updates and PDF attachment handling.
• Smart Explanations: The server returns structured error data that LLMs can easily parse to explain issues in human-readable language.

🛠️ Installation & Usage

Option 1: Using uvx (Recommended)

You can run this server directly without installing it globally:

uvx fintom8-mcp-server

Option 2: Clone and Run

1. Clone this repository:

   git clone https://github.com/Fintom8/fintom8-mcp-server.git
   cd fintom8-mcp-server
   

2. Install dependencies:

   pip install -e .
   

3. Run the server:

   mcp run server.py
   

🔑 Configuration

By default, the server connects to the public Fintom8 endpoints:

• Validation endpoint: https://fintom8platform-dev.ey.r.appspot.com/backend/invoice-agent
• Converter endpoint: https://fintom8converter-prod.ey.r.appspot.com/backend/converter-workflowv2/

To use a specific API environment or authenticated tier, set the environment variables:

export FINTOM_API_URL="https://api.fintom8.com/v1/validate"
export FINTOM_CONVERTER_URL="https://api.fintom8.com/v1/convert"
export FINTOM_API_KEY="your-api-key"

📦 Tools Included

1. convert_pdf_to_invoice: Convert PDF invoices to UBL format

Converts PDF invoice documents to structured UBL/Peppol XML format using AI-powered extraction.

Input:

• pdf_path (string, optional): Path to the PDF file to convert
• pdf_base64 (string, optional): Base64-encoded PDF content
• invoice_format (string, default: "ubl"): Output format for the invoice
• gemini_model (string, default: "gemini-3-flash-preview"): The Gemini model to use
• max_iterations (int, default: 3): Maximum number of AI iterations for refinement
• verbose_output (bool, default: false): Include verbose processing details

Output: JSON containing the converted UBL invoice and conversion metadata

Note: Either pdf_path or pdf_base64 must be provided.

2. validate_invoice: Validate UBL/Peppol XML invoices

Validates a UBL/Peppol XML invoice against EN16931 and Peppol compliance rules.

Input:

• xml_content (string): The raw XML string of the invoice to validate

Output: JSON compliance report (Valid/Invalid, Error List)

� Usage Examples

Example 1: Convert PDF to UBL Invoice

# Using with Claude Desktop or other MCP-compatible client
convert_pdf_to_invoice(
    pdf_path="/path/to/invoice.pdf",
    invoice_format="ubl",
    gemini_model="gemini-3-flash-preview",
    max_iterations=3
)

Example 2: Validate Converted Invoice

# First convert PDF
result = convert_pdf_to_invoice(pdf_path="/path/to/invoice.pdf")

# Then validate the result
validate_invoice(xml_content=result["ubl_xml"])

Example 3: Full Workflow

# 1. Convert PDF to UBL
converted = convert_pdf_to_invoice(
    pdf_path="/invoices/supplier_invoice.pdf",
    verbose_output=True
)

# 2. Validate the converted invoice
validation_result = validate_invoice(xml_content=converted["ubl_xml"])

# 3. Check compliance
if validation_result["is_valid"]:
    print("✅ Invoice is Peppol-compliant!")
else:
    print("❌ Validation errors:", validation_result["errors"])

�🛡️ Privacy & Security

This fintom8-mcp-server acts as a thin client proxy.

• No data processing happens within this repository's code.
• All validation logic is handled secure servers at Fintom8.
• Your data is processed solely for the purpose of validation and is not used for AI model training.

📄 License

MIT License. See LICENSE for details.