Fakturowo MCP by usefulapi
Read invoices, clients and products in Fakturowo; create documents and update payment status.
Should I use this
Quality & Safety
Findings (2)
- LOWTool 'fakturowo_get_next_document_number' name length outside 3-30 rangein fakturowo_get_next_document_number
- LOWTool 'fakturowo_set_document_payment_status' name length outside 3-30 rangein fakturowo_set_document_payment_status
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"fakturowo": {
"url": "https://fakturowo.usefulapi.io/mcp"
}
}
}Remote endpoints
https://fakturowo.usefulapi.io/mcpstreamable-httpWhat it can do
Tool inventory
Tools (9)
🟢fakturowo_list_documents(document_type, seller_tax_id, buyer_tax_id, page)
List invoices and other documents on the account, 100 per page: id (api_numer), type, number, issue and sale date, currency, net/VAT/gross value, seller and buyer, payment status, due date and KSeF number. Filter by document type or by seller/buyer tax number. Values are the vendor's own (dates DD-MM-YYYY; dokument_rodzaj is the type code with a readable name for common types). Fakturowo api_zadanie=3.
Input Schema
{
"type": "object",
"properties": {
"document_type": {
"description": "Only this document type.",
"type": "string",
"enum": [
"vat_invoice",
"proforma",
"advance_invoice",
"final_invoice",
"bill",
"simplified_invoice",
"invoice_no_vat",
"receipt",
"debit_note",
"credit_note",
"invoice_split_payment",
"invoice_cash_method",
"invoice_to_receipt"
]
},
"seller_tax_id": {
"description": "Only documents of the seller with this tax number (NIP).",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z0-9 .\\-/]+$"
},
"buyer_tax_id": {
"description": "Only documents of the buyer with this tax number (NIP).",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z0-9 .\\-/]+$"
},
"page": {
"description": "Page number, from 1 (default 1; 100 rows per page). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fakturowo_get_document(document_id)
One document by its id (api_numer, from fakturowo_list_documents or the id returned when it was created): the header fields and every line item (name, unit, quantity, net/gross price, discount, VAT rate and amount, gross value). Fakturowo api_zadanie=3 with api_numer.
Input Schema
{
"type": "object",
"properties": {
"document_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The document's api_numer."
}
},
"required": [
"document_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fakturowo_get_next_document_number(document_type)
The running number Fakturowo will give the next document of a type (the sequence counter saved on the account). Nothing is created. Fakturowo api_zadanie=8.
Input Schema
{
"type": "object",
"properties": {
"document_type": {
"description": "Document type (default vat_invoice).",
"type": "string",
"enum": [
"vat_invoice",
"proforma",
"advance_invoice",
"final_invoice",
"bill",
"simplified_invoice",
"invoice_no_vat",
"receipt",
"debit_note",
"credit_note",
"invoice_split_payment",
"invoice_cash_method",
"invoice_to_receipt"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fakturowo_list_clients(page)
List the saved clients (contractors), 100 per page: id (api_numer), name, address, tax number, contact details, account number and notes. PESEL and ID-card numbers are never returned. Fakturowo api_zadanie=4.
Input Schema
{
"type": "object",
"properties": {
"page": {
"description": "Page number, from 1 (default 1; 100 rows per page). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fakturowo_get_client(client_id)
One saved client by id (api_numer, from fakturowo_list_clients). PESEL and ID-card numbers are never returned. Fakturowo api_zadanie=4 with api_numer.
Input Schema
{
"type": "object",
"properties": {
"client_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The client's api_numer."
}
},
"required": [
"client_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fakturowo_list_products(page)
List the saved products and services (the catalogue used on documents), 100 per page: id (api_numer), name, unit, VAT rate, net price, gross value, currency, comment, GTU code and discount. Fakturowo api_zadanie=6.
Input Schema
{
"type": "object",
"properties": {
"page": {
"description": "Page number, from 1 (default 1; 100 rows per page). Pass the previous reply's next_page.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100000
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fakturowo_get_product(product_id)
One saved product by id (api_numer, from fakturowo_list_products). Fakturowo api_zadanie=6 with api_numer.
Input Schema
{
"type": "object",
"properties": {
"product_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The product's api_numer."
}
},
"required": [
"product_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴fakturowo_create_document(document_type, seller, buyer, items, issue_date, ...)
WRITE: issue a new document (invoice, proforma, receipt...) on the account. It is saved immediately and takes the next number in its sequence; this tool cannot delete it again, and calling it twice issues two documents. Issue documents one at a time and wait for each reply: Fakturowo says overlapping saves can get the same number when the account's numbering check is off. Needs a buyer and at least one line item; the seller defaults to what the account has saved only if Fakturowo allows that, otherwise pass seller. Returns the new document's id (api_numer); with public_links true also a public PDF and preview link (anyone with the link can open the document). Fakturowo api_zadanie=1.
Input Schema
{
"type": "object",
"properties": {
"document_type": {
"description": "Document type (default vat_invoice).",
"type": "string",
"enum": [
"vat_invoice",
"proforma",
"advance_invoice",
"final_invoice",
"bill",
"simplified_invoice",
"invoice_no_vat",
"receipt",
"debit_note",
"credit_note",
"invoice_split_payment",
"invoice_cash_method",
"invoice_to_receipt"
]
},
"seller": {
"description": "Seller details.",
"type": "object",
"properties": {
"name": {
"description": "Seller company or full name.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"first_name": {
"description": "Seller first name (for a private person with no business name).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"last_name": {
"description": "Seller last name (for a private person with no business name).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"private_person": {
"description": "True for a private person that runs no business (then first and last name are needed).",
"type": "boolean"
},
"tax_id": {
"description": "Seller tax number (NIP, or a VAT id).",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z0-9 .\\-/]+$"
},
"street": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"building": {
"description": "Building number.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"apartment": {
"description": "Apartment/unit number.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"postal_code": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"country": {
"description": "Two-letter country code (PL, DE...), default PL.",
"type": "string",
"minLength": 1,
"maxLength": 60
},
"email": {
"type": "string",
"maxLength": 200,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"phone": {
"type": "string",
"minLength": 1,
"maxLength": 40
}
}
},
"buyer": {
"type": "object",
"properties": {
"name": {
"description": "Buyer company or full name.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"first_name": {
"description": "Buyer first name (for a private person with no business name).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"last_name": {
"description": "Buyer last name (for a private person with no business name).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"private_person": {
"description": "True for a private person that runs no business (then first and last name are needed).",
"type": "boolean"
},
"tax_id": {
"description": "Buyer tax number (NIP, or a VAT id).",
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Za-z0-9 .\\-/]+$"
},
"street": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"building": {
"description": "Building number.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"apartment": {
"description": "Apartment/unit number.",
"type": "string",
"minLength": 1,
"maxLength": 30
},
"postal_code": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"country": {
"description": "Two-letter country code (PL, DE...), default PL.",
"type": "string",
"minLength": 1,
"maxLength": 60
},
"email": {
"type": "string",
"maxLength": 200,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"phone": {
"type": "string",
"minLength": 1,
"maxLength": 40
}
},
"description": "Buyer details."
},
"items": {
"minItems": 1,
"maxItems": 300,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Product or service name."
},
"quantity": {
"description": "Quantity (default 1).",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1000000000
},
"unit": {
"description": "Unit of measure.",
"type": "string",
"enum": [
"service",
"piece",
"day",
"hour",
"kg",
"km",
"set",
"l",
"m",
"m2",
"m3",
"month",
"package",
"pair",
"lump_sum"
]
},
"vat_rate": {
"type": "string",
"minLength": 1,
"maxLength": 10,
"pattern": "^(zw|np|oo|npI|npII|0WDT|0EX|0KR|\\d{1,2}(\\.\\d{1,2})?)$",
"description": "VAT rate as enabled on the account: \"23\", \"8\", \"5\", \"0\", \"zw\" (exempt), \"np\"..."
},
"net_price": {
"description": "Net unit price. Give either net_price or gross_value.",
"type": "number",
"minimum": 0,
"maximum": 1000000000000
},
"gross_value": {
"description": "Gross value of the line (the vendor field is `produkt_wartosc_brutto`). Give either net_price or gross_value.",
"type": "number",
"minimum": 0,
"maximum": 1000000000000
}
},
"required": [
"name",
"vat_rate"
]
},
"description": "Line items (1-300)."
},
"issue_date": {
"description": "Issue date (default today).",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
},
"sale_date": {
"description": "Sale date (default today).",
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$"
},
"place": {
"description": "Place of issue (default: the account's saved place).",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"currency": {
"description": "Currency code (default PLN).",
"type": "string",
"enum": [
"PLN",
"EUR",
"USD",
"GBP",
"CHF",
"CAD",
"AUD",
"JPY",
"THB",
"HKD",
"NZD",
"SGD",
"HUF",
"UAH",
"CZK",
"DKK",
"ISK",
"NOK",
"SEK",
"HRK",
"RON",
"BGN",
"TRY",
"ILS",
"CLP",
"PHP",
"MXN",
"ZAR",
"BRL",
"MYR",
"RUB",
"IDR",
"INR",
"KRW",
"CNY",
"XDR",
"AED"
]
},
"payment_type": {
"description": "Payment method / term.",
"type": "string",
"enum": [
"transfer",
"transfer_7_days",
"transfer_14_days",
"transfer_21_days",
"transfer_30_days",
"transfer_60_days",
"cash_on_delivery",
"cash",
"paid_by_transfer",
"paid_in_cash"
]
},
"payment_status": {
"description": "Payment status (default unpaid).",
"type": "string",
"enum": [
"unpaid",
"paid",
"partially_paid"
]
},
"paid_amount": {
"description": "Amount already paid (subtracted from the total).",
"type": "number",
"minimum": 0,
"maximum": 1000000000000
},
"notes": {
"description": "Notes printed on the document.",
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"public_links": {
"description": "Return public PDF and preview links (default false).",
"type": "boolean"
}
},
"required": [
"buyer",
"items"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴fakturowo_set_document_payment_status(document_id, status, paid_amount)
WRITE: change the payment status of an existing document (unpaid, paid, partially_paid) and optionally the amount already paid. Only those fields are sent; Fakturowo edits the document in place. Fakturowo api_zadanie=1 with api_numer.
Input Schema
{
"type": "object",
"properties": {
"document_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The document's api_numer."
},
"status": {
"type": "string",
"enum": [
"unpaid",
"paid",
"partially_paid"
],
"description": "New payment status."
},
"paid_amount": {
"description": "Amount already paid (for partially_paid, or to record the amount).",
"type": "number",
"minimum": 0,
"maximum": 1000000000000
}
},
"required": [
"document_id",
"status"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Community
Evidence