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.

Related MCP server: mcp-fattura-elettronica-it

🏗️ 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(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 requires signed XML (challenge-response) to obtain a session token. Signing requires a qualified electronic signature or credentials from the MF portal and cannot be automated by this MCP server. The session token must be obtained outside the server and passed via KSEF_SESSION_TOKEN or the session_token parameter of the submit_invoice_to_ksef tool.

Technical documentation for KSeF: https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/

🤖 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.