Content
# Faktuj MCP Server
[](https://www.npmjs.com/package/faktuj-mcp)
[](https://faktuj.pl)
[](https://faktuj.pl/health)
Integrate **[Faktuj](https://faktuj.pl)** into Claude, Cursor, VS Code, and any MCP-compatible AI assistant. Generate [VAT invoices](https://faktuj.pl/faktura-vat) and [proforma invoices](https://faktuj.pl/faktura-proforma), look up companies by NIP, check NBP exchange rates, and validate IBAN numbers — all from your AI workflow. Fully aligned with [KSeF compliance](https://faktuj.pl/ksef) requirements.
No API key required. Free forever.
## Quick Start
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"faktuj": {
"command": "npx",
"args": ["-y", "faktuj-mcp"]
}
}
}
```
Or install globally:
```bash
npm install -g faktuj-mcp
```
Then add to your config:
```json
{
"mcpServers": {
"faktuj": {
"command": "faktuj-mcp"
}
}
}
```
## Available Tools
| Tool | Description |
|------|-------------|
| `generate_invoice` | Generate a Polish [VAT invoice](https://faktuj.pl/faktura-vat) PDF. Pass full invoice JSON with seller, buyer, and line items. Returns invoice number and base64 PDF. |
| `generate_proforma` | Generate a [proforma invoice](https://faktuj.pl/faktura-proforma) 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](https://faktuj.pl/docs). 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](https://faktuj.pl/faktura-vat) — How to create a compliant Polish VAT invoice
- [Proforma Invoice Guide](https://faktuj.pl/faktura-proforma) — When and how to use proforma invoices
- [KSeF Compliance](https://faktuj.pl/ksef) — Poland's National e-Invoicing System requirements
- [Blog](https://faktuj.pl/blog) — Invoicing guides, tax tips, and product updates
- [API Documentation](https://faktuj.pl/docs) — Full REST API reference
## SoftVoyagers Ecosystem
Faktuj is part of the [SoftVoyagers](https://github.com/softvoyagers) open-source portfolio:
| Product | Description | Website |
|---------|-------------|---------|
| **LinkMeta** | Free URL metadata extraction API | [linkmeta.dev](https://linkmeta.dev) |
| **PageShot** | Free screenshot & webpage capture API | [pageshot.site](https://pageshot.site) |
| **PDFSpark** | Free HTML/URL to PDF conversion API | [pdfspark.dev](https://pdfspark.dev) |
| **OGForge** | Free Open Graph image generator API | [ogforge.dev](https://ogforge.dev) |
| **LinkShrink** | Free privacy-first URL shortener API | [linkshrink.dev](https://linkshrink.dev) |
| **Faktuj** | Free Polish VAT invoice generator | [faktuj.pl](https://faktuj.pl) |
| **QRMint** | Free styled QR code generator & API | [qrmint.dev](https://qrmint.dev) |
| **PageDrop** | Free instant HTML hosting API | [pagedrop.dev](https://pagedrop.dev) |
| **PismoSzyteNaMiarę** | Darmowy generator pism urzędowych | [pismoszytenamiare.pl](https://pismoszytenamiare.pl) |
## License
MIT
