{
  "markdown": "# mcp-facture-electronique-fr 🇫🇷\n\n[English](README.md) | [Francais](README.fr.md)\n\n<!-- mcp-name: io.github.cmendezs/mcp-facture-electronique-fr -->\n\n![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-facture-electronique-fr.svg)](https://pypi.org/project/mcp-facture-electronique-fr/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-facture-electronique-fr.svg)](https://pypi.org/project/mcp-facture-electronique-fr/) [![mcp-facture-electronique-fr MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-facture-electronique-fr/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-facture-electronique-fr)\n\nA Python MCP server exposing the standardized **AFNOR XP Z12-013** APIs for the French e-invoicing reform (effective September 1, 2026). This project enables AI agents (Claude, IDEs) to interact natively with the Approved Platform (PA/PDP) ecosystem as a Compatible Solution (SC).\n\n---\n\n## Introduction\n\nThis package is built on top of [**mcp-einvoicing-core**](https://github.com/cmendezs/mcp-einvoicing-core), a shared base library for European e-invoicing MCP servers. It provides the OAuth2 HTTP client, token cache, shared models, logging utilities, and exception hierarchy used by this package.\n\n`mcp-einvoicing-core` is installed automatically as a transitive dependency, no extra step is needed.\n\n> **For contributors:** `pip install -e \".[dev]\"` installs the base package from PyPI automatically.\n\nThis server operates in **Compatible Solution (CS)** mode as defined by the French e-invoicing reform. The CS acts as an intermediary between the company's information system and an Approved Platform (AP/PDP). This means:\n\n- **No profile validation of caller-supplied payloads.** The server transmits the invoice file (Factur-X PDF/A-3, UBL 2.1, or CII XML) as provided. Structural and business-rule validation (NF XP Z12-012 profiles, Schematron rules) is performed by the receiving Approved Platform, not by this server.\n- **No e-reporting payload validation beyond schema-level XSD.** Transaction reports (Flux 10.1/10.3) and payment reports (Flux 10.2/10.4) are validated against the DGFiP v3.2 XSD schema when `validate_ereporting_xml` is called, but deeper business-rule checks (e.g. coherence between declared amounts and invoice totals) are the responsibility of the AP.\n- **No PDF/A-3 envelope generation.** The caller must produce the conformant Factur-X PDF/A-3 file with embedded CII XML. This server transmits the finished binary.\n\nThe Approved Platform performs final validation and may reject non-conformant submissions with an error code and message.\n\n## Installation\n\n### Via PyPI (recommended)\n\n```bash\npip install mcp-facture-electronique-fr\n```\n\nOr without prior installation using `uvx`:\n\n```bash\nuvx mcp-facture-electronique-fr\n```\n\nFor Factur-X Schematron validation (`validate_facturx`, requires the XSLT 2.0 /\nSaxon-HE backend — see FR-XSLT2-1 in Available tools below):\n\n```bash\npip install mcp-facture-electronique-fr[xslt2]\n```\n\n### From source\n\n```bash\n# Clone the repository\ngit clone https://github.com/cmendezs/mcp-facture-electronique-fr.git\ncd mcp-facture-electronique-fr\n\n# Create the virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install in editable mode\npip install -e \".[dev]\"\n```\n\n```bash\n# Initial configuration\ncp .env.example .env\n# Edit .env with the credentials provided by your PA/PDP\n```\n\n## Configuration (.env)\n\nThe server requires the following variables to authenticate with an Approved Platform (PA):\n\n| Variable | Description |\n|----------|-------------|\n| `PA_BASE_URL_FLOW` | Base URL of the PA Flow Service |\n| `PA_BASE_URL_DIRECTORY` | Deprecated — no longer read; see `PPF_ANNUAIRE_BASE_URL` |\n| `PPF_ANNUAIRE_BASE_URL` | Base URL of the PPF Annuaire service (defaults to the production swagger `servers` URL; override for sandbox testing) |\n| `PA_CLIENT_ID` | OAuth2 Client ID |\n| `PA_CLIENT_SECRET` | OAuth2 Client Secret |\n| `PA_TOKEN_URL` | Authentication server URL |\n| `PA_ORGANIZATION_ID` | Organization identifier for multi-tenant AP (optional) |\n| `HTTP_TIMEOUT` | Request timeout (default: 30s) |\n| `PPF_GLOBAL_ID` | PPF party GlobalID for the CDAR second `RecipientTradeParty` (optional; unset by default, see `submit_lifecycle_status`) |\n| `PPF_SCHEME_ID` | schemeID for `PPF_GLOBAL_ID` (default `0238`) |\n| `PPF_NAME` | Name for the PPF `RecipientTradeParty` (default `PPF`) |\n| `PPF_ROLE_CODE` | RoleCode for the PPF `RecipientTradeParty` (default `DFH`) |\n\n## Claude Desktop integration\n\nTo use this server with Claude, add this configuration to your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"facture-electronique-fr\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-facture-electronique-fr\"],\n      \"env\": {\n        \"PA_BASE_URL_FLOW\": \"https://api.votre-pdp.fr/flow\",\n        \"PPF_ANNUAIRE_BASE_URL\": \"https://aife.economie.gouv.fr/ppf/annuaire-public/v1\",\n        \"PA_CLIENT_ID\": \"votre-id\",\n        \"PA_CLIENT_SECRET\": \"votre-secret\",\n        \"PA_TOKEN_URL\": \"https://auth.votre-pdp.fr/oauth/token\"\n      }\n    }\n  }\n}\n```\n\n## Cursor integration\n\nCursor supports MCP servers via stdio. Add the configuration in:\n- **Global** (all projects): `~/.cursor/mcp.json`\n- **Project** (this repository only): `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"facture-electronique-fr\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-facture-electronique-fr\"],\n      \"env\": {\n        \"PA_BASE_URL_FLOW\": \"https://api.votre-pdp.fr/flow\",\n        \"PPF_ANNUAIRE_BASE_URL\": \"https://aife.economie.gouv.fr/ppf/annuaire-public/v1\",\n        \"PA_CLIENT_ID\": \"votre-id\",\n        \"PA_CLIENT_SECRET\": \"votre-secret\",\n        \"PA_TOKEN_URL\": \"https://auth.votre-pdp.fr/oauth/token\"\n      }\n    }\n  }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` then *Reload Window*) to apply the changes.\n\n## Kiro integration\n\nKiro supports MCP servers via its dedicated configuration file. Two levels are available:\n- **Global** (all projects): `~/.kiro/settings/mcp.json`\n- **Workspace** (this repository only): `.kiro/settings/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"facture-electronique-fr\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-facture-electronique-fr\"],\n      \"env\": {\n        \"PA_BASE_URL_FLOW\": \"https://api.votre-pdp.fr/flow\",\n        \"PPF_ANNUAIRE_BASE_URL\": \"https://aife.economie.gouv.fr/ppf/annuaire-public/v1\",\n        \"PA_CLIENT_ID\": \"votre-id\",\n        \"PA_CLIENT_SECRET\": \"votre-secret\",\n        \"PA_TOKEN_URL\": \"https://auth.votre-pdp.fr/oauth/token\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\nThe file is automatically reloaded on save. You can also open the config via the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) then *MCP*.\n\n> **Kiro security tip**: rather than writing secrets in plain text, use the syntax `\"PA_CLIENT_SECRET\": \"${PA_CLIENT_SECRET}\"`, Kiro resolves shell environment variables at startup.\n\n## Available tools\n\n| Service | Domain | Standard | MCP Tools |\n|---------|--------|----------|-----------|\n| **Flow Service** | Invoice flows and e-reporting | Annex A, v1.2.0 | 5 tools |\n| **PPF Annuaire (directory)** | Central directory (SIREN/SIRET/routing/addressing) | PPF swagger v1.11.0 | 20 tools |\n| **Webhook Service** | Event notification subscriptions | Annex A, v1.2.0 | 5 tools |\n| **Factur-X Service** | CII XML validation (Schematron) | Factur-X 1.09.2 | 1 tool |\n\n> Text bumped to June 2026 (v1.2.0 swagger current) — AFNOR resupplied the XP Z12-013\n> narrative text in June 2026 without an updated swagger; the server continues to\n> implement the v1.2.0 wire contract.\n\n> **Note (FR-XSLT2-1, resolved):** the bundled Factur-X 1.09.2 Schematron\n> stylesheets require XSLT 2.0, which `lxml`/`libxslt` (XSLT 1.0 only) cannot\n> compile — the same root cause as the `DE-XSLT2-1` gap tracked for ZUGFeRD.\n> `validate_facturx` now runs real Schematron validation via Saxon-HE. Install\n> the optional `xslt2` extra for this to work:\n> `pip install mcp-facture-electronique-fr[xslt2]`. Without it, the tool\n> degrades gracefully to `level=\"unavailable\"`.\n\n> **Note (FR-FLUX11-2026-06, PPF Annuaire):** the directory tools are wired\n> directly against the bundled PPF-platform swagger\n> `ppf-openapi-annuaire-api-public-1.11.0-openapi.json` — this is a\n> **PPF-platform-specific** interface, not a PDP-agnostic Annex B abstraction.\n> Per the swagger's own description, these endpoints are subject to change and\n> require prior PISTE application publication before use.\n\n### Flow Service (Flow management)\n* `submit_flow`: Submit invoices (**Factur-X**, **UBL**, **CII**) or e-reporting data.\n* `search_flows`: Multi-criteria search of sent or received flows using the standard filters.\n* `submit_lifecycle_status`: Update the lifecycle status (e.g., Made available, Collected, Dispute).\n* `get_flow`: Retrieve the full details and attachments of a specific flow.\n* `healthcheck_flow`: Test the connectivity and availability of the PA Flow API.\n\n### PPF Annuaire (directory)\nWired directly against the bundled PPF-platform swagger\n`ppf-openapi-annuaire-api-public-1.11.0-openapi.json` — see the note above.\n* `search_company` / `get_company_by_siren` / `get_company_by_id_instance`: Look up legal units (SIREN).\n* `search_establishment` / `get_establishment_by_siret` / `get_establishment_by_id_instance`: Look up establishments (SIRET).\n* `search_routing_code` / `get_routing_code_by_siret_and_code` / `get_routing_code_by_id_instance` / `create_routing_code` / `update_routing_code` / `replace_routing_code`: Manage routing codes (code-routage).\n* `search_directory_line` / `get_directory_line_by_code` / `get_directory_line` / `create_directory_line` / `update_directory_line` / `replace_directory_line` / `delete_directory_line`: Manage directory lines (ligne-annuaire), the electronic-invoice receiving addresses.\n* `check_ppf_annuaire_health`: Check availability of the PPF Annuaire service.\n\n### Webhook Service (Webhook management)\n* `list_webhooks`: List all webhook subscription IDs for the current token holder.\n* `get_webhook`: Retrieve the full details of a webhook subscription.\n* `create_webhook`: Subscribe to flow event notifications (filter by flow type, direction, processing rule).\n* `update_webhook`: Update a webhook's technical parameters (authentication, signature).\n* `delete_webhook`: Unsubscribe from a webhook.\n\n## Architecture\n\nThe server acts as an intelligent communication interface between your AI agent and the technical infrastructure of the reform:\n\n```text\n[ ERP / Business IS ] <--> [ MCP Server ] <--> [ Approved Platform (PA/PDP) ]\n          ^                        |\n          |                        v\n   [ AI Agent (Claude) ] <--- (XP Z12-013 Standard)\n```\n\n## Supported standards\n\n- **AFNOR XP Z12-012**: Invoice message formats, profiles, and lifecycle statuses (v1.4, June 2026 edition).\n- **AFNOR XP Z12-013**: Service interface specifications (June 2026 edition; v1.2.0 wire contract).\n- **AFNOR XP Z12-014**: Technical implementation guide for business use cases (v1.4, June 2026 edition).\n- **France B2B reform**: Mandatory rollout schedule (2024-2026).\n\n## Tests\n\n```bash\n# Run the unit and integration test suite\npytest tests/ -v\n```\n\n## Contributing\n\nContributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Other e-invoicing MCP servers\n\n| Country | Server |\n|---------|--------|\n| 🌍 Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |\n| 🇧🇪 Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |\n| 🇧🇷 Brazil | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |\n| 🇫🇷 France | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |\n| 🇩🇪 Germany | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |\n| 🇮🇳 India | [mcp-einvoicing-in](https://github.com/cmendezs/mcp-einvoicing-in) |\n| 🇮🇹 Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |\n| 🇲🇽 Mexico | [mcp-cfdi-mx](https://github.com/cmendezs/mcp-cfdi-mx) |\n| 🇵🇱 Poland | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |\n| 🇸🇬 Singapore | [mcp-invoicenow-sg](https://github.com/cmendezs/mcp-invoicenow-sg) |\n| 🇪🇸 Spain | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |\n| 🇦🇪 United Arab Emirates | [mcp-einvoicing-ae](https://github.com/cmendezs/mcp-einvoicing-ae) |\n\n## License\n\nThis project is distributed under the **Apache 2.0** license. See the [LICENSE](LICENSE) file for details. For the full version history, see [CHANGELOG.md](CHANGELOG.md).\n",
  "bytes": 12733,
  "sha": "2b619188028a0ab3a922b50febaf471e5ea811f18057442bde65b8fc5a3dd74b",
  "repo_slug": "cmendezs/mcp-facture-electronique-fr",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cmendezs_mcp_facture_electroni_7c03ca53/readme"
}