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 |
|---|---|
wfirma_list_companies | GET /user_companies/find |
wfirma_list_invoices | GET /invoices/find |
wfirma_get_invoice | GET /invoices/get/{id} |
wfirma_list_contractors | GET /contractors/find |
wfirma_get_contractor | GET /contractors/get/{id} |
wfirma_list_expenses | GET /expenses/find |
wfirma_get_expense | GET /expenses/get/{id} |
wfirma_list_payments | GET /payments/find |
wfirma_get_payment | GET /payments/get/{id} |
Every company-scoped tool requires the internal companyId returned by
wfirma_list_companies. A Polish NIP is not accepted as a company id.
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 needed
Claude 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.js
Design 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.