MCP server for the iFirma.pl Polish accounting API. Enables AI assistants (Claude, Cursor, Windsurf) to manage invoices, expenses, contractors, and more through natural language.
claude mcp add ifirma \
-e IFIRMA_USERNAME=your@email.pl \
-e IFIRMA_API_KEY_INVOICE=hex_key_faktura \
-e IFIRMA_API_KEY_EXPENSE=hex_key_wydatek \
-e IFIRMA_API_KEY_ACCOUNT=hex_key_abonent \
-e IFIRMA_API_KEY_RECEIPT=hex_key_rachunek \
-- npx -y ifirma-mcp-server
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers" : {
"ifirma" : {
"command" : " npx" ,
"args" : [" -y" , " ifirma-mcp-server" ],
"env" : {
"IFIRMA_USERNAME" : " your@email.pl" ,
"IFIRMA_API_KEY_INVOICE" : " hex_key_faktura" ,
"IFIRMA_API_KEY_EXPENSE" : " hex_key_wydatek" ,
"IFIRMA_API_KEY_ACCOUNT" : " hex_key_abonent" ,
"IFIRMA_API_KEY_RECEIPT" : " hex_key_rachunek"
}
}
}
}
Run via npx -y ifirma-mcp-server with the environment variables below.
Log in to ifirma.pl
Go to Settings > API
Generate keys for: Faktura, Wydatek, Abonent
Copy the hex keys into environment variables
Variable
Required
Description
IFIRMA_USERNAME
Yes
iFirma login (email)
IFIRMA_API_KEY_INVOICE
No*
API key for invoices (faktura)
IFIRMA_API_KEY_EXPENSE
No*
API key for expenses (wydatek)
IFIRMA_API_KEY_ACCOUNT
No*
API key for account operations (abonent)
IFIRMA_API_KEY_RECEIPT
No*
API key for receipts (rachunek)
IFIRMA_DRY_RUN
No
Test mode — logs requests without sending
* At least one API key is required.
Tool
Description
list_invoices
List issued invoices with filters
create_domestic_invoice
Domestic VAT invoice
create_domestic_invoice_non_vat
Domestic invoice for non-VAT payers
create_proforma
Proforma invoice
create_export_invoice
Export invoice
create_wdt_invoice
Intra-community supply (WDT) invoice
create_eu_service_invoice
EU service invoice (art. 28b)
create_foreign_currency_invoice
Foreign currency invoice
create_correction_invoice
Correction invoice
create_receipt_invoice
Receipt invoice (faktura do paragonu)
create_oss_invoice
One Stop Shop invoice
create_ioss_invoice
Import One Stop Shop invoice
send_invoice_email
Send invoice by email
send_invoice_post
Send invoice via postal mail
send_invoice_ksef
Submit invoice to KSeF
Contractors (faktura key)
Tool
Description
search_contractors
Search by name or NIP
get_contractor
Contractor details by ID
create_contractor
Add new contractor
update_contractor
Update contractor (requires all fields)
Tool
Description
register_payment
Register payment against an invoice
Tool
Description
get_eu_vat_rates
EU VAT rates by country code
Tool
Description
create_cost_expense
Business cost with VAT invoice
create_goods_purchase_expense
Goods/materials purchase
create_other_cost_expense
Non-invoice cost (receipt, contract, etc.)
create_telecom_expense
Phone/internet expense
Tool
Description
get_accounting_month
Current accounting month
set_accounting_month
Change accounting month
get_api_limits
Check API rate limits
Tool
Description
create_order
Create e-commerce order
Tool
Description
manage_employee_questionnaire
Employee personal questionnaire
git clone https://github.com/adriandmitroca/ifirma-mcp-server.git
cd ifirma-mcp-server
npm install
npm run dev
npm test # Unit tests (no API access needed)
IFIRMA_DRY_RUN=true npm run dev # Dry-run mode
See CONTRIBUTING.md for more details.
MIT