{
  "markdown": "# mcp-ksef-pl 🇵🇱\n\n[English](README.md) | [Polski](README.pl.md)\n\n<!-- mcp-name: io.github.cmendezs/mcp-ksef-pl -->\n\n![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-ksef-pl.svg)](https://pypi.org/project/mcp-ksef-pl/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-ksef-pl.svg)](https://pypi.org/project/mcp-ksef-pl/)\n[![mcp-ksef-pl MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-ksef-pl/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-ksef-pl)\n\nA Python MCP server providing tools for Polish **electronic invoicing** compliant with **KSeF (FA(2))** and **Peppol BIS Billing 3.0 / EN 16931**. It enables AI agents (Claude, IDEs) to generate, validate, and submit invoices to the Krajowy System e-Faktur (KSeF), as well as validate Polish tax identifiers (NIP and REGON).\n\n---\n\n## Introduction\n\nThis package is built on [**mcp-einvoicing-core**](https://github.com/cmendezs/mcp-einvoicing-core), the shared base library for European e-invoicing MCP servers. It provides an OAuth2 HTTP client, token cache, data models, logging utilities, and an exception hierarchy.\n\n`mcp-einvoicing-core` is installed automatically as a dependency, no additional step is required.\n\n## Installation\n\n### Via PyPI (recommended)\n\n```bash\npip install mcp-ksef-pl\n```\n\nOr without prior installation using `uvx`:\n\n```bash\nuvx mcp-ksef-pl\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cmendezs/mcp-ksef-pl.git\ncd mcp-ksef-pl\nuv sync --all-extras\n```\n\n## Configuration (environment variables)\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `KSEF_ENVIRONMENT` | `test` | KSeF environment: `production` or `test` |\n| `KSEF_SESSION_TOKEN` | — | KSeF session token (obtained through the challenge-response flow with MF) |\n| `KSEF_NIP` | — | NIP of the entity submitting invoices |\n| `KSEF_TIMEOUT` | `30` | HTTP request timeout in seconds |\n| `KSEF_VERIFY_MF_KEY_PINNING` | `false` | Enforce SPKI SHA-256 pinning on the MF encryption certificate. No-op until fingerprints are populated for the active environment, even when set to `true` |\n| `EINVOICING_PEPPOL_CODELIST_DIR` | — | Local directory containing your own copy of the OpenPeppol eDEC Code Lists, required by the Peppol codelist tools (not bundled with this package; see `mcp-einvoicing-core` README) |\n| `EINVOICING_EN16931_CODELIST_DIR` | — | Local directory containing your own copy of the CEF \"Digital Building Blocks\" EN 16931 semantic code lists, required by the EN 16931 codelist tools (not bundled; see `mcp-einvoicing-core` README) |\n\nThe EUSR/TSR reporting and MLS tools additionally require the `[xslt2]` extra (`pip install \"mcp-ksef-pl[xslt2]\"`) for Schematron validation.\n\n## Claude Desktop integration\n\nAdd the following configuration to your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"ksef-pl\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-ksef-pl\"],\n      \"env\": {\n        \"KSEF_ENVIRONMENT\": \"test\",\n        \"KSEF_SESSION_TOKEN\": \"<your-ksef-session-token>\",\n        \"KSEF_NIP\": \"<your-nip>\"\n      }\n    }\n  }\n}\n```\n\n## Cursor integration\n\nCursor supports MCP servers via stdio. Add the configuration to:\n- **Globally** (all projects): `~/.cursor/mcp.json`\n- **Per project** (this repository only): `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"ksef-pl\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-ksef-pl\"],\n      \"env\": {\n        \"KSEF_ENVIRONMENT\": \"test\",\n        \"KSEF_SESSION_TOKEN\": \"<your-ksef-session-token>\",\n        \"KSEF_NIP\": \"<your-nip>\"\n      }\n    }\n  }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` → *Reload Window*) after saving changes.\n\n## Kiro integration\n\nKiro supports MCP servers through a dedicated configuration file:\n- **Globally**: `~/.kiro/settings/mcp.json`\n- **Workspace**: `.kiro/settings/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"ksef-pl\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-ksef-pl\"],\n      \"env\": {\n        \"KSEF_ENVIRONMENT\": \"test\",\n        \"KSEF_SESSION_TOKEN\": \"<your-ksef-session-token>\",\n        \"KSEF_NIP\": \"<your-nip>\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n> **Security tip**: instead of entering the token directly, use the syntax\n> `\"KSEF_SESSION_TOKEN\": \"${KSEF_SESSION_TOKEN}\"`, as Kiro resolves shell environment\n> variables at startup.\n\n## Available tools\n\n### FA(3) / FA(2) invoice handling\n\n| Tool | Description |\n|------|-------------|\n| `generate_fa3_invoice` | Generates a KSeF-compliant FA(3) XML invoice (required for KSeF API v2 submissions) |\n| `generate_fa2_invoice` | Generates a KSeF-compliant FA(2) XML invoice (legacy format, read-only use) |\n| `validate_fa3_invoice` | Validates FA(3) XML: XSD validation and FA(3)-specific business rules |\n| `validate_fa2_invoice` | Validates FA(2) XML: XSD validation (if the schema is available) and business rules |\n| `parse_fa2_invoice` | Parses FA(2) XML into a structured dictionary |\n\nThe official FA(2) and FA(3) XSD schemas ship inside the package (`src/mcp_ksef_pl/schemas/`)\nand are loaded automatically via `importlib.resources` — no manual download or configuration\nis required. `validate_fa2_invoice` and `validate_fa3_invoice` run full XSD validation out\nof the box for every installation.\n\n### KSeF lifecycle\n\n| Tool | Description |\n|------|-------------|\n| `submit_invoice_to_ksef` | Submits an FA(3) invoice to the KSeF platform and returns a reference number |\n| `get_ksef_invoice_status` | Retrieves the processing status of an invoice by its reference number |\n| `search_ksef_invoices` | Searches invoices in KSeF by date range and direction (seller/buyer) |\n\n### Identifier validation\n\n| Tool | Description |\n|------|-------------|\n| `validate_polish_nip` | Validates a NIP (10-digit tax identification number) using a checksum algorithm |\n| `validate_polish_regon` | Validates a REGON (9- or 14-digit registry number) using a checksum algorithm |\n\n### Peppol / EN 16931\n\n| Tool | Description |\n|------|-------------|\n| `generate_peppol_invoice` | Generates a UBL 2.1 invoice compliant with Peppol BIS Billing 3.0 / EN 16931 |\n| `validate_peppol_invoice` | Validates a UBL 2.1 Peppol invoice against the CEN EN 16931 base Schematron rules (`en16931-base-only` scope — does not check the Peppol-specific overlay) |\n\n### Peppol network tools\n\nPeppol participant lookup, service-endpoint lookup, a DNS-only diagnostic, AS4 send, Peppol Directory search, and the OpenPeppol eDEC codelist tools are provided by the shared core Peppol tool plugin (`mcp_einvoicing_core.peppol.tools.register_peppol_tools`), mounted in `server.py` with a Poland-specific identifier adapter: a bare NIP (e.g. `1234563218`) is normalized to the `9945:<digits>` Peppol scheme (`PL:VAT`, per the OpenPeppol eDEC Participant Identifier Schemes code list); an already scheme-qualified identifier (e.g. `9945:1234563218`) passes through unchanged. Use these tools to check PEF (Poland's Peppol Access Point for public-procurement B2G invoicing) registration status ahead of `generate_peppol_invoice`.\n\n`peppol_send` signs outbound messages with a real `wsse:Security` signature as of `mcp-einvoicing-core` v1.20.0 (previously computed and discarded — see CHANGELOG.md v0.8.0).\n\n| Tool | Description |\n|------|-------------|\n| `peppol_lookup_participant` | Check whether a business is registered on the Peppol network; returns registration status and supported document types |\n| `peppol_get_service_endpoint` | Fetch the AS4 endpoint for a participant's document type |\n| `resolve_peppol_dns` | DNS-only (SML) diagnostic, independent of SMP reachability |\n| `peppol_send` | Transmit a UBL/CII invoice via AS4 |\n| `peppol_directory_search` | Search the public Peppol Directory by participant, name, country, or document type |\n| `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`) |\n| `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 |\n\nSee the [`mcp-einvoicing-core` README](https://github.com/cmendezs/mcp-einvoicing-core#readme) for full parameter documentation on these tools.\n\n### Peppol reporting and status tools\n\nAdded in v0.8.0 via three opt-in core plugins, mounted unconditionally in `server.py`. Each raises a clear error at call time (not at registration) if its extra or data directory is missing.\n\n| Tool | Plugin | Description |\n|------|--------|-------------|\n| `validate_eusr_report` | `register_peppol_reporting_tools` | Validate an End User Statistics Report (XSD, then Schematron). Requires the `[xslt2]` extra. |\n| `validate_tsr_report` | `register_peppol_reporting_tools` | Validate a Transaction Statistics Report (XSD, then Schematron). Requires the `[xslt2]` extra. |\n| `validate_mls_message` | `register_peppol_mls_tools` | Validate a Message Level Status document (UBL `ApplicationResponse-2` subset). Requires the `[xslt2]` extra. |\n| `build_mls_message` | `register_peppol_mls_tools` | Build a document-level MLS response. Requires the `[xslt2]` extra. |\n| 13 `list_*`/`check_*` pairs, `get_en16931_codelist_version` | `register_en16931_codelist_tools` | EN 16931 semantic code list lookups/checks (units, VAT categories, etc.). Require `EINVOICING_EN16931_CODELIST_DIR`. |\n\nSee the [`mcp-einvoicing-core` README](https://github.com/cmendezs/mcp-einvoicing-core#readme) for full parameter documentation on these tools.\n\n## KSeF authentication\n\nKSeF API v2 uses a multi-step challenge/redeem flow to issue an AccessToken. This MCP server accepts an already-obtained token and cannot automate the signing step (it requires a qualified electronic signature).\n\n### Step-by-step flow\n\n1. **Account setup.** Register at the KSeF portal: https://ksef.mf.gov.pl/. Select the target environment (test or production). The test environment is at `https://ksef-test.mf.gov.pl/`.\n\n2. **Request a challenge.** Call the KSeF API to obtain a challenge XML envelope:\n\n   ```bash\n   curl -s https://ksef-test.mf.gov.pl/auth/challenge \\\n     -H \"Accept: application/json\" \\\n     -d '{\"contextIdentifier\": {\"type\": \"onip\", \"identifier\": \"YOUR_NIP\"}}' \\\n     -H \"Content-Type: application/json\"\n   ```\n\n   The response contains a `challenge` string and a `timestamp`.\n\n3. **Sign the challenge.** Build an `<InitSessionTokenRequest>` XML envelope containing the challenge, then sign it with your qualified e-signature. Accepted signing tools:\n\n   - Qualified e-signature providers: KIR (Szafir), Certum, Sigillum\n   - `podpis.gov.pl` (government signing portal)\n   - Profil Zaufany (Trusted Profile): https://www.podatki.gov.pl/ksef/\n\n   Example using `xmlsec1` with a PKCS#12 certificate:\n\n   ```bash\n   # Build the challenge XML (template at specs/przyklad-wyzwania.xml)\n   xmlsec1 --sign --pkcs12 your-cert.p12 --pwd \"password\" \\\n     --output signed-challenge.xml challenge-template.xml\n   ```\n\n4. **Submit the signed challenge.** POST the signed XML to receive an `authOperation` reference:\n\n   ```bash\n   curl -s https://ksef-test.mf.gov.pl/auth/xades-signature \\\n     -H \"Content-Type: application/octet-stream\" \\\n     --data-binary @signed-challenge.xml\n   ```\n\n5. **Redeem the AccessToken.** Exchange the authenticated operation for an AccessToken:\n\n   ```bash\n   curl -s https://ksef-test.mf.gov.pl/auth/token/redeem \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: Bearer <referenceNumber-or-authOperation-token-from-step-4>\"\n   ```\n\n   The response contains `accessToken.token` and `accessToken.context.referenceNumber`.\n\n6. **Set the token.** Export the token for this MCP server:\n\n   ```bash\n   export KSEF_SESSION_TOKEN=\"<the AccessToken from step 5>\"\n   ```\n\n   The token is valid for approximately 2 hours from issuance (per MF documentation). After expiry, repeat steps 2-5.\n\n### References\n\n- KSeF technical documentation: https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/\n- Authentication spec (CIRFMF): https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md\n- Interactive session spec (CIRFMF): https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md\n- FA(3) migration announcement: `specs/ksef-v2-fa3-migration-announcement-20250630.pdf`\n\n## Architecture\n\nThe server acts as an intelligent communication interface between the AI agent and the KSeF platform and the Peppol network:\n\n```text\n[ ERP System / Application ] <--> [ MCP Server ] <--> [ KSeF (MF) / Peppol Network ]\n          ^                           |\n          |                           v\n   [ AI Agent (Claude) ] <--- (FA(2) / EN 16931)\n```\n\n## Tests\n\n```bash\n# Run unit tests\nuv run pytest 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.\nSee the [LICENSE](LICENSE) file for details. For the full version history, see [CHANGELOG.md](CHANGELOG.md).\n",
  "bytes": 14232,
  "sha": "931e5f1b208ea08699b39eeb28601b6fc81396d39d3b3496b072b6ad63fc12a2",
  "repo_slug": "cmendezs/mcp-ksef-pl",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cmendezs_mcp_ksef_pl_3971cb3b/readme"
}