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 What are my unpaid invoices from last month?"
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
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 --lockedThis 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-keychainEnter 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 scriptsAvailable Tools
9 toolsget_contractorARead-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_declarationARead-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_invoiceARead-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_registerARead-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_registerBRead-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_declarationsARead-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_expensesBRead-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_invoicesARead-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_statusARead-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
wFirma.pl (Polish accounting) via MCP: invoices, contractors, payments, reports. Full read-write.
iFirma MCP server for ChatGPT, Claude and any AI agent: issue invoice, send invoice, send to KSeF, add cost and list unpaid invoices in your own iFirma account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to iFirma yourself; Cotlet does not store your password and you need no iFirma API key. About the official iFirma API: Yes. iFirma has a documented JSON API that issues invoices, lists them, records payments, sends them by email and to KSeF, and adds cost documents (checked 14 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/ifirma-api-mcp-server
Connect ChatGPT and Claude to Fortnox: invoices, customers, reports. Every write needs your OK.
Connect Claude or Cursor to books, invoices, bills, payroll, and sealed closes.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceProvides 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
- AlicenseAqualityCmaintenanceRead-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.11MIT
- AlicenseAqualityDmaintenanceProvides read-only access to wFirma company data, invoices, contractors, expenses, and payments, letting AI assistants query the wFirma API v2 without modifying records.934 npm1MIT
- 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-