mcp-ksef-pl 🇵🇱

English | Polski

A 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).

Built on

This package is built on 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.

mcp-einvoicing-core is installed automatically as a dependency, no additional step is required.

🏗️ Architecture

The server acts as an intelligent communication interface between the AI agent and the KSeF platform and the Peppol network:

[ ERP System / Application ] <--> [ MCP Server ] <--> [ KSeF (MF) / Peppol Network ]
          ^                           |
          |                           v
   [ AI Agent (Claude) ] <--- (FA(2) / EN 16931)

🛠️ Available tools

FA(3) / FA(2) invoice handling

KSeF lifecycle

Identifier validation

Peppol / EN 16931

🚀 Installation

Via PyPI (recommended)

pip install mcp-ksef-pl

Or without prior installation using uvx:

uvx mcp-ksef-pl

From source

git clone https://github.com/cmendezs/mcp-ksef-pl.git
cd mcp-ksef-pl
uv sync --all-extras

⚙️ Configuration (environment variables)

🔐 KSeF authentication

KSeF 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).

Step-by-step flow

1. 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/.

2. Request a challenge. Call the KSeF API to obtain a challenge XML envelope:

   bash

   curl -s https://ksef-test.mf.gov.pl/api/online/Session/AuthorisationChallenge \
     -H "Accept: application/json" \
     -d '{"contextIdentifier": {"type": "onip", "identifier": "YOUR_NIP"}}' \
     -H "Content-Type: application/json"
   

   The response contains a challenge string and a timestamp.

3. Sign the challenge. Build an <InitSessionTokenRequest> XML envelope containing the challenge, then sign it with your qualified e-signature. Accepted signing tools:

   • Qualified e-signature providers: KIR (Szafir), Certum, Sigillum
   • podpis.gov.pl (government signing portal)
   • Profil Zaufany (Trusted Profile): https://www.podatki.gov.pl/ksef/

   Example using xmlsec1 with a PKCS#12 certificate:

   bash

   # Build the challenge XML (template at specs/przyklad-wyzwania.xml)
   xmlsec1 --sign --pkcs12 your-cert.p12 --pwd "password" \
     --output signed-challenge.xml challenge-template.xml
   

4. Submit the signed challenge. POST the signed XML to obtain an AccessToken:

   bash

   curl -s https://ksef-test.mf.gov.pl/api/online/Session/AuthoriseXades \
     -H "Content-Type: application/octet-stream" \
     --data-binary @signed-challenge.xml
   

   The response contains sessionToken.token (the AccessToken) and sessionToken.context.referenceNumber.

5. Set the token. Export the token for this MCP server:

   bash

   export KSEF_SESSION_TOKEN="<the AccessToken from step 4>"
   

   The token is valid for approximately 2 hours from issuance (per MF documentation). After expiry, repeat steps 2-4.

References

• KSeF technical documentation: https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/
• Authentication spec (CIRFMF): https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md
• Interactive session spec (CIRFMF): https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md
• FA(3) migration announcement: specs/ksef-v2-fa3-migration-announcement-20250630.pdf

🤖 Claude Desktop integration

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      }
    }
  }
}

⌨️ Cursor integration

Cursor supports MCP servers via stdio. Add the configuration to:

• Globally (all projects): ~/.cursor/mcp.json
• Per project (this repository only): .cursor/mcp.json

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      }
    }
  }
}

Reload the Cursor window (Ctrl+Shift+P → Reload Window) after saving changes.

🪐 Kiro integration

Kiro supports MCP servers through a dedicated configuration file:

• Globally: ~/.kiro/settings/mcp.json
• Workspace: .kiro/settings/mcp.json

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Security tip: instead of entering the token directly, use the syntax "KSEF_SESSION_TOKEN": "${KSEF_SESSION_TOKEN}", as Kiro resolves shell environment variables at startup.

📋 XSD schema (FA_VAT_v1-0E.xsd)

Full XSD validation requires the official schema from the Ministry of Finance. Without it, validate_fa2_invoice only executes business rules.

1. Go to: https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/
2. Download the FA(2) technical documentation package
3. Place the FA_VAT_v1-0E.xsd file in the src/mcp_ksef_pl/schemas/ directory

The file is excluded from the repository (.gitignore), it must be downloaded manually. Helper script: scripts/download_schemas.sh

🧪 Tests

# Run unit tests
uv run pytest tests/ -v

Other e-invoicing MCP servers

📄 License

This project is distributed under the Apache 2.0 license. See the LICENSE file for details.

Project maintained by cmendezs. For questions about the KSeF or Peppol implementation, open an Issue.