Fakturka Api

npm version Website API Status

Integrate Faktuj into Claude, Cursor, VS Code, and any MCP-compatible AI assistant. Generate VAT invoices and proforma invoices, look up companies by NIP, check NBP exchange rates, and validate IBAN numbers — all from your AI workflow. Fully aligned with KSeF compliance requirements.

No API key required. Free forever.

Quick Start

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "faktuj": {
      "command": "npx",
      "args": ["-y", "faktuj-mcp"]
    }
  }
}

Or install globally:

npm install -g faktuj-mcp

Then add to your config:

{
  "mcpServers": {
    "faktuj": {
      "command": "faktuj-mcp"
    }
  }
}

Available Tools

Tool	Description
generate_invoice	Generate a Polish VAT invoice PDF. Pass full invoice JSON with seller, buyer, and line items. Returns invoice number and base64 PDF.
generate_proforma	Generate a proforma invoice PDF. Same schema as VAT invoice. Returns invoice number and base64 PDF.
preview_invoice	Preview and validate invoice data without generating a PDF. Returns validated data or validation errors.
lookup_nip	Look up a Polish company by NIP tax identification number. Returns company name, address, and registration data.
lookup_nbp_rate	Look up NBP (National Bank of Poland) exchange rate for a given currency and date.
validate_iban	Validate an IBAN number. Returns validation result and bank details if valid.

Example Usage

Ask your AI assistant:

• "Generate a VAT invoice from ACME sp. z o.o. (NIP: 1234567890) to Beta S.A. for 10 hours of consulting at 200 PLN/h"
• "Look up the company with NIP 5263442510"
• "What was the EUR/PLN exchange rate on 2026-03-20?"
• "Validate IBAN PL61109010140000071219812874"

Architecture

AI Assistant <--stdio--> faktuj-mcp <--HTTPS--> faktuj.pl REST API

This is a thin stdio MCP transport layer over the Faktuj REST API. The MCP server translates tool calls into HTTP requests and returns structured responses.

Configuration

Environment Variable	Default	Description
FAKTUJ_API_URL	https://faktuj.pl	Base URL for the Faktuj API

Resources

• VAT Invoice Guide — How to create a compliant Polish VAT invoice
• Proforma Invoice Guide — When and how to use proforma invoices
• KSeF Compliance — Poland's National e-Invoicing System requirements
• Blog — Invoicing guides, tax tips, and product updates
• API Documentation — Full REST API reference

SoftVoyagers Ecosystem

Faktuj is part of the SoftVoyagers open-source portfolio:

Product	Description	Website
LinkMeta	Free URL metadata extraction API	linkmeta.dev
PageShot	Free screenshot & webpage capture API	pageshot.site
PDFSpark	Free HTML/URL to PDF conversion API	pdfspark.dev
OGForge	Free Open Graph image generator API	ogforge.dev
LinkShrink	Free privacy-first URL shortener API	linkshrink.dev
Faktuj	Free Polish VAT invoice generator	faktuj.pl
QRMint	Free styled QR code generator & API	qrmint.dev
PageDrop	Free instant HTML hosting API	pagedrop.dev
PismoSzyteNaMiarę	Darmowy generator pism urzędowych	pismoszytenamiare.pl

License

MIT