Faktuj MCP Server

Name: fakturka-api-mcp
Author: softvoyagers

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

fakturka-api-mcp

Faktuj MCP Server

Quick Start

Available Tools

Example Usage

Architecture

Configuration

Resources

SoftVoyagers Ecosystem

License

Resources

Latest Blog Posts

MCP directory API