wFirma MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wFirma MCP Show my recent invoices and which ones are unpaid."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
wFirma MCP
Unofficial, read-only MCP server for the wFirma API v2
(api2.wfirma.pl). Gives MCP-compatible AI assistants typed, read-only access
to company data, invoices, contractors, expenses, and payments — with
credentials that never leave your machine and no commercial middleware between
you and wFirma.
Not affiliated with wFirma. "wFirma" is a trademark of its respective owner.
Tools (9, all read-only)
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Every company-scoped tool requires the internal companyId returned by
wfirma_list_companies. A Polish NIP is not accepted as a company id.
Related MCP server: InvoiceNinja MCP Server
Why read-only
The server intentionally contains no add, edit, delete, send, fiscalization,
KSeF, or payment-mutation operation. The full list of excluded categories,
reviewed against the official documentation at
doc.wfirma.pl, is recorded in
coverage-manifest.json. If you need writes, use
wFirma's own tooling — not this server.
Setup
Credentials
wFirma API keys are created in your wFirma panel (Integrations → API). Required environment variables:
WFIRMA_ACCESS_KEYWFIRMA_SECRET_KEYWFIRMA_APP_KEY
See .env.example. Never commit real values.
Build
pnpm install
pnpm build # → dist/index.js (self-contained esbuild bundle)
pnpm test # all HTTP traffic is mocked; no live account neededClaude Desktop / any 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.jsDesign notes
No runtime dependencies beyond the MCP SDK and zod. The client uses Node's stdlib
httpswith a hard 20s timeout and a bounded response-size guard.Fail-closed error taxonomy. Missing credentials, non-numeric company ids, oversized responses, and auth failures each raise a distinct
wfirma_*error code instead of a generic failure.No PII in logs. Tool parameters are never logged.
Coverage manifest.
coverage-manifest.jsonmaps every tool to its endpoint, risk class, and the test that proves it; a CI test enforces the manifest stays in sync with the source.
License
Available Tools
9 toolswfirma_get_contractorGet wFirma contractorARead-onlyIdempotent
Read one contractor from one explicitly selected wFirma client company.
Inputs: id (required), companyId (required).
wfirma_get_expenseGet wFirma expenseARead-onlyIdempotent
Read one expense from one explicitly selected wFirma client company.
Inputs: id (required), companyId (required).
wfirma_get_invoiceGet wFirma invoiceARead-onlyIdempotent
Read one invoice from one explicitly selected wFirma client company.
Inputs: id (required), companyId (required).
wfirma_get_paymentGet wFirma paymentARead-onlyIdempotent
Read one payment from one explicitly selected wFirma client company.
Inputs: id (required), companyId (required).
wfirma_list_companiesList wFirma companiesARead-onlyIdempotent
Discover the client companies available to this wFirma accounting-office account. Returns internal company ids and NIPs separately.
Inputs: no named parameters.
wfirma_list_contractorsList wFirma contractorsARead-onlyIdempotent
List contractors for one explicitly selected wFirma client company.
Inputs: companyId (required), page, limit.
wfirma_list_expensesList wFirma expensesARead-onlyIdempotent
List expenses for one explicitly selected wFirma client company.
Inputs: companyId (required), page, limit.
wfirma_list_invoicesList wFirma invoicesARead-onlyIdempotent
List invoices for one explicitly selected wFirma client company.
Inputs: companyId (required), page, limit.
wfirma_list_paymentsList wFirma paymentsARead-onlyIdempotent
List payments for one explicitly selected wFirma client company.
Inputs: companyId (required), page, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool maps to a distinct resource and action: list/get pairs for expenses, invoices, contractors, and payments, plus a separate company discovery tool. There is no meaningful overlap between resources, and the list/get distinction is clear.
All tool names follow the same `wfirma_list_<resource>` or `wfirma_get_<resource>` pattern. The naming is predictable and consistent across the entire server.
Nine tools is well-scoped for this server: four entities each have list/get operations, plus one company discovery tool. Nothing feels redundant or excessive.
The server provides complete read-side coverage for expenses, invoices, contractors, and payments, with company discovery to support scoping. The only minor gap is the absence of write operations, but the descriptions suggest this is an intentionally read-focused accounting data access server.
Maintenance
Related MCP Connectors
wFirma.pl (Polish accounting) via MCP: invoices, contractors, payments, reports. Full read-write.
Invoicing, costs, KPiR, VAT and KSeF data from your Mobilna Faktura account (Poland).
Read-only by architecture: ask AI about QuickBooks, Xero and NetSuite, across every entity.
Read-only NuMetric.work accounting & ERP data: statements, KPIs, reports, invoices, documents.
Related MCP Servers
- AlicenseAqualityCmaintenanceLook up Polish companies from any AI assistant: registry data (KRS, REGON, CEIDG), VAT white list checks before payments, and financial statements of 4.4M businesses. Read-only tools backed by official public registers.4MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to InvoiceNinja data, including invoices, expenses, clients, and tax reports, for AI assistants like Claude.1-
- FlicenseNot gradedqualityCmaintenanceProvides read-only access to inv.bg invoicing data, enabling users to list clients and invoices and retrieve full document details and line items through natural language in Claude.1-
- AlicenseAqualityBmaintenanceEnables read-only access to wFirma accounting data—invoices, expenses, contractors, and declarations—through natural language in MCP clients like Claude or Codex.9MIT