Vyfakturuj MCP by usefulapi
Read and create Vyfakturuj invoices and contacts: search, number series, payment methods, tags.
Should I use this
Quality & Safety
Findings (1)
- LOWTool 'vyfakturuj_list_payment_methods' name length outside 3-30 rangein vyfakturuj_list_payment_methods
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": {
"vyfakturuj": {
"url": "https://vyfakturuj.usefulapi.io/mcp"
}
}
}Remote endpoints
https://vyfakturuj.usefulapi.io/mcpstreamable-httpWhat it can do
Tool inventory
Tools (10)
🟢vyfakturuj_list_invoices(q, id_customer, type, number, VS, ...)
Search documents (faktury, zalohove faktury, proformy, objednavky ...); pass sort=date_created~desc for the newest first. Each row has id, number, type, dates, customer, VS, currency, total, flags and flags_decoded (paid, sent_to_customer, cancelled, ...) and the public/PDF URLs; use vyfakturuj_get_invoice for the whole document with items. Filter by free text q, customer id, document type, number, variable symbol (VS), currency or creation date range. Paged with rows_limit/rows_offset. GET /invoice/.
Input Schema
{
"type": "object",
"properties": {
"q": {
"description": "Free-text search over the invoices.",
"type": "string",
"maxLength": 255
},
"id_customer": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "Only invoices of this address-book contact (from vyfakturuj_list_contacts)."
},
"type": {
"description": "Document type: 1 faktura, 2 zalohova faktura, 4 proforma, 8 vyzva k platbe, 16 danovy doklad, 32 opravny danovy doklad, 64 prijmovy doklad, 128 opravny doklad, 512 objednavka.",
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 4
},
{
"type": "number",
"const": 8
},
{
"type": "number",
"const": 16
},
{
"type": "number",
"const": 32
},
{
"type": "number",
"const": 64
},
{
"type": "number",
"const": 128
},
{
"type": "number",
"const": 512
}
]
},
"number": {
"description": "Exact document number.",
"type": "string",
"maxLength": 50
},
"VS": {
"description": "Variable symbol (variabilni symbol).",
"type": "string",
"pattern": "^[0-9]{1,10}$"
},
"currency": {
"description": "Currency, ISO 4217, e.g. CZK, EUR.",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"date_created_from": {
"description": "Created on or after this date (yyyy-mm-dd).",
"type": "string"
},
"date_created_to": {
"description": "Created on or before this date (yyyy-mm-dd).",
"type": "string"
},
"sort": {
"description": "Sort: column~asc or column~desc, several joined by | (for example date_created~desc|number~asc).",
"type": "string",
"pattern": "^[A-Za-z_]{1,40}~(asc|desc)(\\|[A-Za-z_]{1,40}~(asc|desc))*$"
},
"rows_limit": {
"description": "Rows to return, 1-100 (default 25).",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"rows_offset": {
"description": "Rows to skip (default 0). Use next_offset from the previous reply.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_get_invoice(id)
One document with all fields: supplier and customer blocks, items (text, quantity, unit_price, vat_rate, totals), dates, VS, bank details, total, flags and flags_decoded, payment method, public page, PDF and online-payment URLs. GET /invoice/{id}/.
Input Schema
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "The invoice id (from vyfakturuj_list_invoices)."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴vyfakturuj_create_invoice(items, type, id_customer, customer_name, customer_firstname, ...)
WRITE. Creates a document in Vyfakturuj. Vyfakturuj has NO draft state: the document is issued at once and takes the next number of its number series (delete or cancel it in Vyfakturuj if wrong). Does NOT send an e-mail to the customer, does NOT mark it paid and moves no money; automatic reminders and paid notices are switched off for it (disable_automated_mails). Name the customer with id_customer (an address-book contact, from vyfakturuj_list_contacts) or with the customer_* fields. Items need text and unit_price. Optional id_number_series / id_payment_method come from vyfakturuj_list_number_series / vyfakturuj_list_payment_methods; the account defaults apply otherwise. Prices are net unless calculate_vat is 2 (gross). POST /invoice/.
Input Schema
{
"type": "object",
"properties": {
"items": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Item text (max 255 characters)."
},
"unit_price": {
"type": "number",
"minimum": -1000000000,
"maximum": 1000000000,
"description": "Price per unit, in the invoice currency. Net or gross depending on calculate_vat."
},
"quantity": {
"description": "Quantity (default 1).",
"type": "number",
"minimum": -1000000000,
"maximum": 1000000000
},
"unit": {
"description": "Unit, e.g. ks, kg, hod (max 10 characters).",
"type": "string",
"maxLength": 10
},
"vat_rate": {
"description": "VAT rate in percent, e.g. 21, 12 or 0.",
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"text",
"unit_price"
]
},
"description": "Document items (1-200)."
},
"type": {
"description": "Document type: 1 faktura (default), 2 zalohova faktura, 4 proforma faktura, 8 vyzva k platbe, 512 objednavka.",
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 4
},
{
"type": "number",
"const": 8
},
{
"type": "number",
"const": 512
}
]
},
"id_customer": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "Address-book contact id (from vyfakturuj_list_contacts); fills the customer block."
},
"customer_name": {
"description": "Customer company name (when no id_customer).",
"type": "string",
"maxLength": 100
},
"customer_firstname": {
"description": "Customer first name.",
"type": "string",
"maxLength": 100
},
"customer_lastname": {
"description": "Customer last name.",
"type": "string",
"maxLength": 100
},
"customer_IC": {
"description": "Customer ICO (company id).",
"type": "string",
"maxLength": 20
},
"customer_DIC": {
"description": "Customer DIC (VAT id).",
"type": "string",
"maxLength": 20
},
"customer_street": {
"description": "Customer street.",
"type": "string",
"maxLength": 50
},
"customer_city": {
"description": "Customer city.",
"type": "string",
"maxLength": 50
},
"customer_zip": {
"description": "Customer postal code (PSC).",
"type": "string",
"maxLength": 10
},
"customer_country_code": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "ISO 3166 country code, e.g. CZ, SK, DE."
},
"id_number_series": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "Number series id (from vyfakturuj_list_number_series); must match the document type."
},
"id_payment_method": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "Payment method id (from vyfakturuj_list_payment_methods)."
},
"date_created": {
"description": "Issue date yyyy-mm-dd (default today).",
"type": "string"
},
"date_taxable_supply": {
"description": "Date of taxable supply (DUZP) yyyy-mm-dd.",
"type": "string"
},
"days_due": {
"description": "Days until due (splatnost).",
"type": "integer",
"minimum": 0,
"maximum": 3650
},
"currency": {
"description": "Currency, ISO 4217 (default: the account's).",
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"calculate_vat": {
"description": "1 items are net (VAT added), 2 items are gross, 3 special VAT regime, 4 domestic reverse charge, 5 not a VAT payer, 6 foreign reverse charge.",
"anyOf": [
{
"type": "number",
"const": 1
},
{
"type": "number",
"const": 2
},
{
"type": "number",
"const": 3
},
{
"type": "number",
"const": 4
},
{
"type": "number",
"const": 5
},
{
"type": "number",
"const": 6
}
]
},
"language": {
"description": "Language of the document.",
"type": "string",
"enum": [
"cs",
"sk",
"en",
"de",
"it",
"pl"
]
},
"VS": {
"description": "Variable symbol (default: derived from the number).",
"type": "integer",
"minimum": 0,
"maximum": 9999999999
},
"order_number": {
"description": "Order id / reference.",
"type": "string",
"maxLength": 255
},
"text_before_items": {
"description": "Text before the items.",
"type": "string",
"maxLength": 255
},
"text_invoice_footer": {
"description": "Text in the footer.",
"type": "string",
"maxLength": 255
},
"note_internal": {
"description": "Internal note (not on the document).",
"type": "string",
"maxLength": 2000
}
},
"required": [
"items"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_list_contacts(q, IC, DIC, name, mail_to, ...)
Search the address book (adresar): id, name, company, ICO (IC), DIC, address, e-mail (mail_to), phone, default days_due. Filter by free text q, ICO, DIC, name, e-mail or phone. Paged with rows_limit/rows_offset. GET /contact/.
Input Schema
{
"type": "object",
"properties": {
"q": {
"description": "Free-text search.",
"type": "string",
"maxLength": 255
},
"IC": {
"description": "Exact ICO (company id).",
"type": "string",
"maxLength": 20
},
"DIC": {
"description": "Exact DIC (VAT id).",
"type": "string",
"maxLength": 20
},
"name": {
"description": "Address-book name.",
"type": "string",
"maxLength": 100
},
"mail_to": {
"description": "E-mail address of the contact.",
"type": "string",
"maxLength": 100
},
"tel": {
"description": "Phone number.",
"type": "string",
"maxLength": 30
},
"sort": {
"description": "Sort: column~asc or column~desc, several joined by | (for example date_created~desc|number~asc).",
"type": "string",
"pattern": "^[A-Za-z_]{1,40}~(asc|desc)(\\|[A-Za-z_]{1,40}~(asc|desc))*$"
},
"rows_limit": {
"description": "Rows to return, 1-100 (default 25).",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"rows_offset": {
"description": "Rows to skip (default 0). Use next_offset from the previous reply.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_get_contact(id)
One address-book contact with every field (billing and delivery address, ICO/DIC, e-mails, default texts and days_due). GET /contact/{id}/.
Input Schema
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "The contact id (from vyfakturuj_list_contacts)."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴vyfakturuj_create_contact(name, company, firstname, lastname, IC, ...)
WRITE. Adds a contact to the address book (it is not a customer message: nothing is sent). Give at least a name (the address-book label) or company or last name. Returns the new contact with its id. POST /contact/.
Input Schema
{
"type": "object",
"properties": {
"name": {
"description": "Address-book name (how it is listed).",
"type": "string",
"maxLength": 100
},
"company": {
"description": "Company name.",
"type": "string",
"maxLength": 100
},
"firstname": {
"description": "First name.",
"type": "string",
"maxLength": 100
},
"lastname": {
"description": "Last name.",
"type": "string",
"maxLength": 100
},
"IC": {
"description": "ICO (company id).",
"type": "string",
"maxLength": 20
},
"DIC": {
"description": "DIC (VAT id).",
"type": "string",
"maxLength": 20
},
"street": {
"description": "Street.",
"type": "string",
"maxLength": 50
},
"city": {
"description": "City.",
"type": "string",
"maxLength": 50
},
"zip": {
"description": "Postal code (PSC).",
"type": "string",
"maxLength": 10
},
"country_code": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "ISO 3166 country code, e.g. CZ, SK, DE."
},
"tel": {
"description": "Phone.",
"type": "string",
"maxLength": 30
},
"web": {
"description": "Web.",
"type": "string",
"maxLength": 100
},
"mail_to": {
"description": "E-mail where invoices and reminders go.",
"type": "string",
"maxLength": 100,
"pattern": "^[^\\s@,;]+@[^\\s@,;]+$"
},
"days_due": {
"description": "Default days until due for this contact.",
"type": "integer",
"minimum": 0,
"maximum": 3650
},
"note": {
"description": "Your note about the contact.",
"type": "string",
"maxLength": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_get_template(id)
One template / recurring invoice (sablona, pravidelna faktura) by id: its items, customer, schedule and settings. The API has no list endpoint for templates, so the id comes from the user (the number in the template's URL in Vyfakturuj). GET /template/{id}/.
Input Schema
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9][0-9]{0,14}$"
}
],
"description": "The template id."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_list_payment_methods
The payment methods of the account (id_payment_method, name, type: 1 bank transfer, 2 cash, 4 cash on delivery, 8 card, ...). Use the id in vyfakturuj_create_invoice. GET /settings/payment-method/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_list_number_series
The numbering series (ciselne rady) of the account: id_number_series, the document type it is for, name and the number pattern. Use the id in vyfakturuj_create_invoice. GET /settings/number-series/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢vyfakturuj_list_tags
The tags (stitky) of the account: id_tag, name and colour. Invoices carry an id_tag. GET /settings/tags/.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Community
Evidence