{"id":50227643,"url":"https://github.com/cmendezs/mcp-ksef-pl","last_synced_at":"2026-08-28T03:15:03.224Z","repository":{"id":357838992,"uuid":"1215114430","full_name":"cmendezs/mcp-ksef-pl","owner":"cmendezs","description":"Model Context Protocol (MCP) server for Polish Electronic Invoicing (KSeF / FA(2)). Provides tools to validate, generate, and explore API specifications for KSeF interoperability.","archived":false,"fork":false,"pushed_at":"2026-08-14T13:12:47.000Z","size":865,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-08-14T16:37:08.900Z","etag":null,"topics":["e-invoicing","fa2","faktura-elektroniczna","ksef","ksef-api","mcp","mcp-server","poland"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmendezs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit/__init__.py","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"claude":null,"gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2026-04-19T13:56:35.000Z","updated_at":"2026-08-14T13:14:25.000Z","dependencies_parsed_at":"2026-08-14T15:15:40.837Z","dependency_job_id":null,"html_url":"https://github.com/cmendezs/mcp-ksef-pl","commit_stats":null,"previous_names":["cmendezs/mcp-ksef-pl"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/cmendezs/mcp-ksef-pl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-ksef-pl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-ksef-pl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-ksef-pl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-ksef-pl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmendezs","download_url":"https://codeload.github.com/cmendezs/mcp-ksef-pl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-ksef-pl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36948614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-28T02:00:06.244Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["e-invoicing","fa2","faktura-elektroniczna","ksef","ksef-api","mcp","mcp-server","poland"],"created_at":"2026-05-26T16:40:09.152Z","updated_at":"2026-08-28T03:15:03.215Z","avatar_url":"https://github.com/cmendezs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-ksef-pl 🇵🇱\n\n[English](README.md) | [Polski](README.pl.md)\n\n\u003c!-- mcp-name: io.github.cmendezs/mcp-ksef-pl --\u003e\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## Built on\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---\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 ] \u003c--\u003e [ MCP Server ] \u003c--\u003e [ KSeF (MF) / Peppol Network ]\n          ^                           |\n          |                           v\n   [ AI Agent (Claude) ] \u003c--- (FA(2) / EN 16931)\n```\n\n---\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\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:\u003cdigits\u003e` 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---\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---\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---\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---\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 `\u003cInitSessionTokenRequest\u003e` 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 \u003creferenceNumber-or-authOperation-token-from-step-4\u003e\"\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=\"\u003cthe AccessToken from step 5\u003e\"\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---\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\": \"\u003cyour-ksef-session-token\u003e\",\n        \"KSEF_NIP\": \"\u003cyour-nip\u003e\"\n      }\n    }\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\": \"\u003cyour-ksef-session-token\u003e\",\n        \"KSEF_NIP\": \"\u003cyour-nip\u003e\"\n      }\n    }\n  }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` → *Reload Window*) after saving changes.\n\n---\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\": \"\u003cyour-ksef-session-token\u003e\",\n        \"KSEF_NIP\": \"\u003cyour-nip\u003e\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n\u003e **Security tip**: instead of entering the token directly, use the syntax\n\u003e `\"KSEF_SESSION_TOKEN\": \"${KSEF_SESSION_TOKEN}\"`, as Kiro resolves shell environment\n\u003e variables at startup.\n\n---\n\n## 📋 XSD schema\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---\n\n## 🧪 Tests\n\n```bash\n# Run unit tests\nuv run pytest tests/ -v\n```\n\n---\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| 🇮🇹 Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |\n| 🇵🇱 Poland | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |\n| 🇪🇸 Spain | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |\n\n---\n\n## 📄 License\n\nThis project is distributed under the **Apache 2.0** license.\nSee the [LICENSE](LICENSE) file for details.\n\n---\n*Project maintained by cmendezs. For questions about the KSeF or Peppol implementation, open an Issue.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmendezs%2Fmcp-ksef-pl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmendezs%2Fmcp-ksef-pl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmendezs%2Fmcp-ksef-pl/lists"}