Skip to main content
Glama
wFirma MCP

wFirma MCP

by agente-dev

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.

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_KEY

  • WFIRMA_SECRET_KEY

  • WFIRMA_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 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

Available Tools

9 tools
wfirma_get_contractorGet wFirma contractorA
Read-onlyIdempotent

Read one contractor from one explicitly selected wFirma client company.

Inputs: id (required), companyId (required).

wfirma_get_expenseGet wFirma expenseA
Read-onlyIdempotent

Read one expense from one explicitly selected wFirma client company.

Inputs: id (required), companyId (required).

wfirma_get_invoiceGet wFirma invoiceA
Read-onlyIdempotent

Read one invoice from one explicitly selected wFirma client company.

Inputs: id (required), companyId (required).

wfirma_get_paymentGet wFirma paymentA
Read-onlyIdempotent

Read one payment from one explicitly selected wFirma client company.

Inputs: id (required), companyId (required).

wfirma_list_companiesList wFirma companiesA
Read-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 contractorsA
Read-onlyIdempotent

List contractors for one explicitly selected wFirma client company.

Inputs: companyId (required), page, limit.

wfirma_list_expensesList wFirma expensesA
Read-onlyIdempotent

List expenses for one explicitly selected wFirma client company.

Inputs: companyId (required), page, limit.

wfirma_list_invoicesList wFirma invoicesA
Read-onlyIdempotent

List invoices for one explicitly selected wFirma client company.

Inputs: companyId (required), page, limit.

wfirma_list_paymentsList wFirma paymentsA
Read-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

    A4.1/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow the same `wfirma_list_<resource>` or `wfirma_get_<resource>` pattern. The naming is predictable and consistent across the entire server.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Look 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.
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to InvoiceNinja data, including invoices, expenses, clients, and tax reports, for AI assistants like Claude.
      1
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides 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
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables read-only access to wFirma accounting data—invoices, expenses, contractors, and declarations—through natural language in MCP clients like Claude or Codex.
      9
      MIT