Konfiguracja serwera MCP

Czym jest MCP

Model Context Protocol (MCP) to otwarty standard komunikacji między asystentami AI a zewnętrznymi narzędziami. Ksefnik udostępnia serwer MCP, który pozwala AI operować na fakturach KSeF i wyciągach bankowych.

┌──────────────────┐     stdio      ┌──────────────────┐     SDK      ┌──────────────┐
│  Asystent AI     │ ◄────────────► │  Serwer MCP      │ ◄──────────► │  @ksefnik/   │
│  (Claude, etc.)  │   JSON-RPC     │  (@ksefnik/mcp)  │              │  core         │
└──────────────────┘                └──────────────────┘              └──────────────┘

Serwer MCP to cienka warstwa, która tłumaczy wywołania narzędzi MCP na metody SDK @ksefnik/core.

Konfiguracja

Claude Desktop

Edytuj plik ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) lub %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "1234567890",
        "KSEF_TOKEN": "eyJhbGciOi...",
        "KSEF_ENV": "demo"
      }
    }
  }
}

Cursor

Utwórz plik .cursor/mcp.json w katalogu projektu:

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "1234567890",
        "KSEF_TOKEN": "eyJhbGciOi..."
      }
    }
  }
}

Claude Code

claude mcp add ksefnik -- npx -y @ksefnik/mcp

Lub dodaj do .claude/settings.json:

{
  "mcpServers": {
    "ksefnik": {
      "command": "npx",
      "args": ["-y", "@ksefnik/mcp"],
      "env": {
        "KSEF_NIP": "1234567890",
        "KSEF_TOKEN": "eyJhbGciOi..."
      }
    }
  }
}

Testowanie

1. Uruchom serwer ręcznie, aby sprawdzić czy działa
2. Sprawdź logi w kliencie AI

# Test ręczny -- serwer powinien uruchomić się bez błędów
npx @ksefnik/mcp

Uwaga

Serwer MCP wymaga poprawnie skonfigurowanego NIP i tokena do pracy z prawdziwym KSeF. Bez tokena (KSEF_TOKEN) serwer automatycznie przełącza się na wbudowany symulator — idealne do testowania i nauki, ale dane będą fikcyjne.

Dostępne narzędzia

Narzędzie	Opis
sync-invoices	Synchronizacja faktur z KSeF
import-bank	Import wyciągu bankowego
reconcile	Uzgadnianie faktur z przelewami
get-unmatched	Nieuzgodnione pozycje z raportu
query-invoices	Wyszukiwanie faktur
send-invoice	Wysyłka faktury do KSeF
validate-invoice	Walidacja faktury
confirm-match	Potwierdzenie dopasowania
get-upo	Sprawdzenie statusu UPO (potwierdzenie odbioru)

Każde narzędzie opisane jest szczegółowo na osobnej stronie.