Wfirma Mcp

io.github.agente-devPublished by GitHub account agente-devv1.0.0Updated Oct 24, 2026

Unofficial read-only MCP server for the wFirma API v2: invoices, contractors, expenses, payments.

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Unofficial read-only MCP server that gives an AI assistant typed access to wFirma company data: invoices, contractors, expenses and payments.

What you can do
List companies and retrieve the internal company ID needed by other tools, since a Polish NIP is not accepted as a company ID. List and fetch individual invoices. List and fetch individual contractors. List and fetch individual expenses. List and fetch individual payments.
When to use it
Useful when you want an assistant to look up or summarize wFirma accounting records — invoices, contractors, expenses or payments — without leaving the chat, and you only need read access. Not suitable if you need to create, edit, send or fiscalize documents.
Requirements
Runs locally as a Node.js stdio process (npm package wfirma-mcp, or a built bundle). Needs three wFirma API credentials set as environment variables: WFIRMA_ACCESS_KEY, WFIRMA_SECRET_KEY and WFIRMA_APP_KEY, created in the wFirma panel under Integrations → API. Network access to the wFirma API v2 endpoint is required.
Before you install
Requires three secret credentials (WFIRMA_ACCESS_KEY, WFIRMA_SECRET_KEY, WFIRMA_APP_KEY); keep them out of committed files. It is read-only by design and contains no add, edit, delete, send, fiscalization or payment operations. Company financial and contractor data is sent to the wFirma API and returned to the assistant. It is unofficial and not affiliated with wFirma.

Installation

In SourceWeft

  1. Open Wfirma Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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)

ToolEndpoint
wfirma_list_companiesGET /user_companies/find
wfirma_list_invoicesGET /invoices/find
wfirma_get_invoiceGET /invoices/get/{id}
wfirma_list_contractorsGET /contractors/find
wfirma_get_contractorGET /contractors/get/{id}
wfirma_list_expensesGET /expenses/find
wfirma_get_expenseGET /expenses/get/{id}
wfirma_list_paymentsGET /payments/find
wfirma_get_paymentGET /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_KEY
  • WFIRMA_SECRET_KEY
  • WFIRMA_APP_KEY

See .env.example. Never commit real values.

Build

bash
pnpm installpnpm 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

json
{  "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)

bash
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 https with 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.json maps 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

MIT

Source: README.md at commit 00214de

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts