mcp-ksef-pl 🇵🇱

Serwer MCP w Pythonie udostępniający narzędzia do polskiej faktury elektronicznej zgodnej z KSeF (FA(2)) i Peppol BIS Billing 3.0 / EN 16931. Umożliwia agentom AI (Claude, IDE) generowanie, walidację i przesyłanie faktur do Krajowego Systemu e-Faktur (KSeF), a także weryfikację identyfikatorów podatkowych NIP i REGON.

English: This is a Model Context Protocol (MCP) server for Polish electronic invoicing. It implements the KSeF FA(2) national invoice format and the Peppol BIS Billing 3.0 / EN 16931 cross-border format, enabling AI agents to generate, validate, submit, and query invoices via the Krajowy System e-Faktur (KSeF) platform, and to validate Polish tax identifiers (NIP, REGON).

Built on

Ten pakiet jest zbudowany na bazie mcp-einvoicing-core — wspólnej biblioteki bazowej dla europejskich serwerów MCP do fakturowania elektronicznego. Dostarcza ona klienta HTTP OAuth2, pamięć podręczną tokenów, modele danych, narzędzia do logowania i hierarchię wyjątków.

mcp-einvoicing-core jest instalowane automatycznie jako zależność — nie jest wymagany dodatkowy krok.

🏗️ Architektura

Serwer pełni rolę inteligentnego interfejsu komunikacyjnego między agentem AI a platformą KSeF oraz siecią Peppol:

[ System ERP / Aplikacja ] <--> [ Serwer MCP ] <--> [ KSeF (MF) / Sieć Peppol ]
          ^                           |
          |                           v
   [ Agent AI (Claude) ] <--- (FA(2) / EN 16931)

🛠️ Dostępne narzędzia

Obsługa faktur FA(2)

Cykl życia w KSeF

Walidacja identyfikatorów

Peppol / EN 16931

🚀 Instalacja

Przez PyPI (zalecane)

pip install mcp-ksef-pl

Lub bez wcześniejszej instalacji z uvx:

uvx mcp-ksef-pl

Ze źródeł

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

⚙️ Konfiguracja (zmienne środowiskowe)

🔐 Uwierzytelnianie w KSeF

KSeF wymaga podpisanego XML (challenge-response) do uzyskania tokenu sesji. Podpisanie wymaga kwalifikowanego podpisu elektronicznego lub poświadczeń z portalu MF i nie może być zautomatyzowane przez ten serwer MCP. Token sesji należy uzyskać poza serwerem i przekazać przez KSEF_SESSION_TOKEN lub parametr session_token narzędzia submit_invoice_to_ksef.

Dokumentacja techniczna KSeF: https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/

🤖 Integracja z Claude Desktop

Dodaj poniższą konfigurację do pliku claude_desktop_config.json:

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

⌨️ Integracja z Cursor

Cursor obsługuje serwery MCP przez stdio. Dodaj konfigurację do:

• Globalnie (wszystkie projekty): ~/.cursor/mcp.json
• Projekt (tylko to repozytorium): .cursor/mcp.json

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

Przeładuj okno Cursor (Ctrl+Shift+P → Reload Window) po zapisaniu zmian.

🪐 Integracja z Kiro

Kiro obsługuje serwery MCP przez dedykowany plik konfiguracyjny:

• Globalnie: ~/.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": "<twój-token-sesji-ksef>",
        "KSEF_NIP": "<twój-nip>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Wskazówka bezpieczeństwa: zamiast wpisywać token wprost, użyj składni "KSEF_SESSION_TOKEN": "${KSEF_SESSION_TOKEN}" — Kiro rozwiązuje zmienne środowiskowe powłoki przy uruchomieniu.

📋 Schemat XSD (FA_VAT_v1-0E.xsd)

Pełna walidacja XSD wymaga oficjalnego schematu Ministerstwa Finansów. Bez niego validate_fa2_invoice wykonuje wyłącznie reguły biznesowe.

1. Przejdź na stronę: https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/
2. Pobierz pakiet dokumentacji technicznej FA(2)
3. Umieść plik FA_VAT_v1-0E.xsd w katalogu src/mcp_ksef_pl/schemas/

Plik jest wykluczony z repozytorium (.gitignore) — należy go pobrać ręcznie. Pomocniczy skrypt: scripts/download_schemas.sh

🧪 Testy

# Uruchom testy jednostkowe
uv run pytest tests/ -v

Other e-invoicing MCP servers

📄 Licencja

Ten projekt jest dystrybuowany na licencji Apache 2.0. Szczegóły w pliku LICENSE.

Projekt utrzymywany przez cmendezs. W przypadku pytań dotyczących implementacji KSeF lub Peppol otwórz Issue.