wFirma MCP

Inoffizieller, schreibgeschützter MCP-Server für die wFirma API v2 (api2.wfirma.pl). Bietet MCP-kompatiblen KI-Assistenten typisierten, schreibgeschützten Zugriff auf Firmendaten, Rechnungen, Kontrahenten, Ausgaben und Zahlungen – mit Zugangsdaten, die Ihren Rechner nie verlassen, und ohne kommerzielle Middleware zwischen Ihnen und wFirma.

Nicht mit wFirma verbunden. „wFirma" ist eine Marke des jeweiligen Inhabers.

Tools (9, alle schreibgeschützt)

Jedes Tool mit Firmenbezug erfordert die interne companyId, die von wfirma_list_companies zurückgegeben wird. Eine polnische NIP wird nicht als Firmen-ID akzeptiert.

Related MCP server: InvoiceNinja MCP Server

Warum schreibgeschützt?

Der Server enthält bewusst keine Operationen zum Hinzufügen, Bearbeiten, Löschen, Senden, Fiskalisieren, für KSeF oder für Zahlungsänderungen. Die vollständige Liste der ausgeschlossenen Kategorien, die anhand der offiziellen Dokumentation unter doc.wfirma.pl geprüft wurde, ist in coverage-manifest.json festgehalten. Wenn Sie Schreibzugriff benötigen, verwenden Sie die eigenen Werkzeuge von wFirma – nicht diesen Server.

Einrichtung

Zugangsdaten

wFirma-API-Schlüssel werden in Ihrem wFirma-Panel erstellt (Integrationen → API). Erforderliche Umgebungsvariablen:

• WFIRMA_ACCESS_KEY

• WFIRMA_SECRET_KEY

• WFIRMA_APP_KEY

Siehe .env.example. Committen Sie niemals echte Werte.

Build

pnpm install
pnpm build      # → dist/index.js (self-contained esbuild bundle)
pnpm test       # all HTTP traffic is mocked; no live account needed

Claude Desktop / beliebiger stdio-MCP-Client

{
  "mcpServers": {
    "wfirma": {
      "command": "node",
      "args": ["/absolute/path/to/wfirma-mcp/dist/index.js"],
      "env": {
        "WFIRMA_ACCESS_KEY": "your-access-key",
        "WFIRMA_SECRET_KEY": "your-secret-key",
        "WFIRMA_APP_KEY": "your-app-key"
      }
    }
  }
}

Claude Code / Cursor (scope: project)

claude mcp add wfirma -- node /absolute/path/to/wfirma-mcp/dist/index.js

Design-Hinweise

• Keine Laufzeitabhängigkeiten außer dem MCP SDK und zod. Der Client verwendet die https-Standardbibliothek von Node mit einem festen 20s-Timeout und einer Begrenzung der Antwortgröße.

• Fail-closed-Fehlerklassifizierung. Fehlende Zugangsdaten, nicht-numerische Firmen-IDs, zu große Antworten und Authentifizierungsfehler erzeugen jeweils einen eigenen wfirma_*-Fehlercode anstelle eines allgemeinen Fehlers.

• Keine personenbezogenen Daten (PII) in Logs. Tool-Parameter werden niemals protokolliert.

• Coverage-Manifest. coverage-manifest.json ordnet jedem Tool seinen Endpunkt, seine Risikoklasse und den zugehörigen Test zu; ein CI-Test stellt sicher, dass das Manifest mit dem Quellcode synchron bleibt.

Lizenz

MIT