See llms.txt for all machine-readable content.

Back to Templates

Connect Claude or ChatGPT via MCP to wFirma invoicing and KSeF

Created by

Created by: Romuald Członkowski || aiadvisors
Romuald Członkowski

Last update

Last update a day ago

Categories

Quick overview

Connect Claude, ChatGPT or any MCP client to wFirma, the Polish invoicing and accounting service. Nine tools cover about 40 API modules: search and edit invoices, contractors, payments and expenses, read the official API docs live and save PDFs to Google Drive, with a guard for irreversible KSeF actions.

How it works

  1. An MCP Server Trigger with n8n User Auth (OAuth2) exposes 9 tools. Users sign in with their n8n account, and only people allowed to run the workflow can connect.
  2. Every tool calls a gateway inside the same workflow ($workflow.id), so you import one file. The Plan node builds the wFirma API URL and checks whether the call needs approval; Route sends it to the API, the approval guard or the docs branch.
  3. For API calls, the XML node converts the request into wFirma's XML format, the HTTP Request node sends it, and the answer is parsed back into clean JSON with ok, status, records and pagination.
  4. If wFirma rate-limits a read (find/get), the workflow waits 35 seconds and retries once. Writes are never retried automatically.
  5. Deleting records, e-mailing invoices, fiscalization and final invoices (sent to KSeF, irreversible) need confirmed=true. Without it the server returns CONFIRMATION_REQUIRED, so the model must ask the user first. Drafts, pro forma invoices and offers go through directly.
  6. wfirma_docs fetches the official wFirma Postman collection and returns the module's fields and XML examples as Markdown, so the model uses correct field names before writing.
  7. wfirma_download_pdf saves the invoice or document PDF to your Google Drive folder and returns the link to the file.

Setup

  1. Create a Custom Auth credential with {"headers":{"accessKey":"…","secretKey":"…","appKey":"…"}}. Generate accessKey and secretKey in wFirma (Ustawienia → Bezpieczeństwo → Aplikacje → Klucze API) and request the appKey from wFirma. Select the credential in the wFirma API and Download PDF nodes.
  2. In the Config node, set drive_folder_id to the Google Drive folder for PDFs. Set company_id only if your login has several companies; you can find it with wfirma_find on module user_companies.
  3. Select your Google Drive credential in the Upload PDF to Drive node.
  4. Activate the workflow, copy the MCP URL from the MCP Server Trigger, add it to your MCP client and log in with your n8n account.

Requirements

  • n8n with the MCP Server Trigger v2 or newer
  • A wFirma account with API keys (accessKey, secretKey) and an appKey from wFirma
  • A Google Drive credential (only for saving PDFs)
  • An MCP client that supports OAuth, such as Claude or ChatGPT

Customization

  • Change which operations need confirmation in the needs_confirmation field of the Plan node
  • Switch the MCP Server Trigger to Bearer auth if your client does not support OAuth
  • Add shortcut tools by copying a tool node and fixing its module and action
  • Replace the Google Drive node to store PDFs somewhere else

Additional info

The official wFirma API docs are in Polish, so wfirma_docs returns Polish field descriptions; tool descriptions and messages are in English
Invoice drafts created through the API are not sent to KSeF; only final invoice types are, and those need confirmed=true
Keep per-tool approval on in your MCP client for the write tools