Skip to main content
Glama
wfirma-mcp

wfirma-mcp

by tajchert

wFirma MCP

Your accounting, one conversation away.

Connect wFirma to Claude, Codex, or any MCP client. Ask about invoices, expenses, contractors, and declarations in plain language. Your assistant reads the records directly, so you can skip the exports and copy-paste.

  • Nine accounting tools covering invoices, expenses, PIT/VAT/JPK/ZUS declarations, and revenue/VAT registers.

  • Read-only accounting access — records stay unchanged; login and filters can update session or saved-view settings.

  • Runs on your computer with your wFirma login. macOS Keychain support keeps credentials out of config files.

Try asking

Show my invoices for last month. Separate drafts and tell me if more pages are available.

Open this invoice and show its line items, VAT breakdown, and contractor details.

Pokaż ewidencję przychodów za ostatni miesiąc, z podziałem na stawki ryczałtu.

Related MCP server: ordis-mcp-server

Quick start

Requires Python 3.11+, uv, Git, and a wFirma account with password login. Supports macOS, Linux, and Windows.

1. Install

git clone https://github.com/tajchert/wfirma-mcp.git
cd wfirma-mcp
uv sync --locked

This Python server uses uv. The commands below launch the installed executable directly, so your assistant needs no package manager on its PATH.

2. Add your login

macOS — save it to Keychain once:

uv run --locked wfirma-mcp --setup-keychain

Enter your wFirma login and password in your terminal. The password is masked; allow Keychain access if macOS asks.

Copy .env.example to .env and fill in WFIRMA_LOGIN and WFIRMA_PASSWORD locally. On macOS/Linux, run chmod 600 .env. On Windows, restrict access through the file's Security settings.

Append --env-file /absolute/path/to/wfirma-mcp/.env to the client commands below. For Claude Desktop, replace "args": [] with:

"args": ["--env-file", "/absolute/path/to/wfirma-mcp/.env"]

The file contains plaintext credentials; keep it private. .env is never loaded automatically. A saved macOS Keychain entry takes precedence; add --credential-source plain to bypass it. More credential options.

3. Connect your assistant

Replace /absolute/path/to/wfirma-mcp with your checkout's full path. On Windows, use C:\path\to\wfirma-mcp\.venv\Scripts\wfirma-mcp.exe; double the backslashes inside JSON strings.

Codex

codex mcp add wfirma -- "/absolute/path/to/wfirma-mcp/.venv/bin/wfirma-mcp"

Restart or reconnect Codex after registration. Codex MCP guide.

Claude Code

claude mcp add --transport stdio --scope user wfirma -- "/absolute/path/to/wfirma-mcp/.venv/bin/wfirma-mcp"

Run /mcp in Claude Code to check the connection. Claude Code MCP guide.

Claude Desktop

Open Settings → Developer → Edit Config and add the wfirma entry to claude_desktop_config.json. Keep any existing servers.

{
  "mcpServers": {
    "wfirma": {
      "command": "/absolute/path/to/wfirma-mcp/.venv/bin/wfirma-mcp",
      "args": []
    }
  }
}

Save, fully quit, and reopen Claude Desktop. Desktop setup guide.

First message: “Use wFirma to check my active company, then show last month's invoices.” Your assistant starts the server automatically. Keep the checkout at its configured path.

What to know

  • Uses wFirma's browser interface; no official API key is needed. Browser changes may affect compatibility. MFA/CAPTCHA are not supported yet.

  • Lists return the current page and report whether more records exist. Saved filters can narrow results; ask your assistant to check the period and completeness before summarizing.

  • Supports reading records. Invoice creation, payments, declaration submission, PDFs, company switching, and tax calculations are not available.

  • Credentials stay local; session cookies stay in memory. Retrieved accounting data is shared with your connected assistant. Privacy details.

Reference & development

All tools and advanced setup · Browser interface · MIT license

uv run pytest -q
uv run ruff check src tests scripts

Available Tools

9 tools
get_contractorA
Read-onlyIdempotent

Read contractor basics using an ID from an invoice contractor link, not a company ID.

Inputs: contractor_id (required). Returns: id, fields, company_id

get_declarationA
Read-onlyIdempotent

Read a declaration dialog. JPK returns a namespaced XML tree; PIT keeps calculation tables.

Inspect the document's actual period and version. Correction supersession is unresolved.

Inputs: declaration_id (required). Returns: id, xml, text, tables, +1 more

get_invoiceA
Read-onlyIdempotent

Read an invoice detail dialog by a returned ID; preserves independent detail tables.

Inputs: invoice_id (required). Returns: id, xml, text, tables, +1 more

get_revenue_registerA
Read-onlyIdempotent

Read the ryczałt revenue register for year+month, or the saved view if both omitted.

Inputs: year, month. Returns: rows, model, period, filters, +6 more

get_vat_registerB
Read-onlyIdempotent

Read the VAT sale/purchase register for its saved period; inspect period and complete.

Inputs: kind. Returns: rows, model, period, filters, +6 more

list_declarationsA
Read-onlyIdempotent

Read declarations for the saved period. VAT can mean VAT-UE; JPK has payable VAT.

Current page only. ZUS components remain separate. Paid/remaining is bookkeeping state.

Inputs: kind. Returns: rows, model, period, filters, +6 more

list_expensesB
Read-onlyIdempotent

Read the saved booked-expense or expense-draft view. Current page only; check complete.

Filters and booked-expense details are not validated. Currency display text is retained.

Inputs: drafts. Returns: rows, model, period, filters, +6 more

list_invoicesA
Read-onlyIdempotent

Read one invoice page, including drafts. Supply year+month OR both ISO dates.

Without filters, use the saved view. Check period, other saved filters and complete; date-range boundary semantics and accounting recognition dates are not established.

Inputs: year, month, date_to, date_from. Returns: rows, model, period, filters, +6 more

session_statusA
Read-onlyIdempotent

Log in if needed and verify the active company. Never returns credentials or tokens.

Inputs: no named parameters. Returns: company_id, authenticated, company_pinned, accounting_access

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: get_* tools read singular details while list_* tools read collections, and the two register tools are separated by tax type. There is no meaningful overlap between tool purposes, and the descriptions reinforce the boundaries.

    Naming Consistency4/5

    The tools follow a consistent snake_case pattern with get_ for single-object reads and list_ for collection reads. The only deviation is session_status, which breaks the verb_noun pattern and would be more consistent as get_session_status.

    Tool Count5/5

    Nine tools is a well-scoped size for an accounting data integration. Each tool earns its place by covering a distinct aspect of the domain, and the count is neither bloated nor too thin.

    Completeness4/5

    The surface covers core read operations for invoices, declarations, expenses, registers, contractors, and session state. Minor gaps exist: there is no contractor listing, no expense detail tool, and writes are entirely absent, but this may be intentional for a read-only reporting bridge.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides structured, read-mostly access to small-business back-office data including customers, invoices, and account notes, allowing Claude to query overdue invoices, revenue summaries, and more.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Read-only MCP server for the Ordis accounting API, exposing 11 typed tools to query financial data such as invoices, tax forms, KPIs, and more directly from Claude.
      11
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides read-only access to wFirma company data, invoices, contractors, expenses, and payments, letting AI assistants query the wFirma API v2 without modifying records.
      9
      34 npm
      1
      MIT
    • 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
      -