fakturownia-mcp

MCP (Model Context Protocol) server exposing a Fakturownia (InvoiceOcean) account as tools for Claude and other MCP clients: invoices (list/search, create, update, status changes, PDF download), clients and products.

Built on fakturownia-client — the API token is sent only in the Authorization: Bearer header, never in URLs. All tools are async, and every write goes through an approval gate.

There is deliberately no invoice-delete tool (destructive on financial records); use change_invoice_status instead.

Configuration

Two required environment variables (values from Fakturownia: Ustawienia → Ustawienia konta → Integracja):

Related MCP server: KSeF MCP

Setup

Claude Code

claude mcp add fakturownia \
  -e FAKTUROWNIA_DOMAIN=mycompany \
  -e FAKTUROWNIA_API_TOKEN=... \
  -- uvx fakturownia-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "fakturownia": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["fakturownia-mcp"],
      "env": {
        "FAKTUROWNIA_DOMAIN": "mycompany",
        "FAKTUROWNIA_API_TOKEN": "..."
      }
    }
  }
}

Any other MCP client / no uv

The server speaks MCP over stdio. Any of these commands starts it:

uvx fakturownia-mcp                  # zero-install, recommended
pip install fakturownia-mcp && fakturownia-mcp
python -m fakturownia_mcp            # after pip install

MCP Inspector (interactive testing)

npx @modelcontextprotocol/inspector \
  -e FAKTUROWNIA_DOMAIN=... -e FAKTUROWNIA_API_TOKEN=... \
  uvx fakturownia-mcp

Tools

Parameters are fully typed (Pydantic) — date patterns, pagination limits and status enums are enforced in the tool JSON Schema before any API call.

Example prompts once connected:

• "List my unpaid invoices from this month"

• "Show my expenses from June" → list_invoices(income=false, ...)

• "Issue a VAT invoice for ACME for 'Consulting', 1000 zł net" → approval dialog → created

• "Mark invoice 52572/07/2026 as paid"

• "Download the PDF of my latest invoice"

Approval gate for writes (🔒)

Every mutating tool asks for confirmation via MCP elicitation before touching the API — clients with elicitation support (Claude Code, Claude Desktop, MCP Inspector) show a native approval dialog describing the exact operation (e.g. "create vat invoice for ACME with positions: Consulting"). Declining aborts the call before any request is sent.

Clients without elicitation support get a clear error instead; set FAKTUROWNIA_SKIP_CONFIRM=1 to run without the gate.

Troubleshooting

• "command not found" in Claude Desktop — GUI apps don't inherit your shell's PATH; use the full path to uvx (which uvx).

• "Missing environment variables" tool error — the server starts without credentials and validates them on first use; check both env vars in your client config.

• HTTP 401 on every call — wrong FAKTUROWNIA_API_TOKEN or wrong account subdomain in FAKTUROWNIA_DOMAIN.

• A new release doesn't show up — uvx caches installs; run uvx fakturownia-mcp@latest once (or pin fakturownia-mcp==X.Y.Z).

• Product price update seems ignored — Fakturownia quirk: send price_net and price_gross together; a lone price_net is ignored by the API.

License

MIT