Billomat MCP Server — 145 tools
The Billomat DADL turns Billomat's API into an MCP server that Claude, GPT or any MCP-compatible agent can consume directly. One YAML file declares all 145 tools — invoice, offer, credit, confirmation, delivery, recurring, and more — and ToolMesh serves them at runtime. No Python boilerplate, no per-endpoint code, no separate MCP server process.
Below: the endpoint coverage matrix, a two-block ToolMesh setup, the full tool reference grouped by Billomat feature area.
Source: Billomat REST API
Which Billomat endpoints are covered?
58% (145 of ~250 endpoints)
Focus: Billomat invoicing: invoices (items, payments, comments, tags), offers (estimates, quotes), credit notes, recurring invoices, clients (contacts), articles, taxes, units, suppliers, incoming invoices.
Missing: article property values, client/supplier property values, inbox documents, activity feed, webhooks, templates CRUD (read-only here), settings write beyond read, letters, digital signature upload, postal mail (Pixelletter), encashment
How do you configure the Billomat DADL?
- Log in to your Billomat account at https://{billomatID}.billomat.net
- Open Settings > Employees (Einstellungen > Mitarbeiter) and select your user
- Enable API access for the user — a personal API key is generated
- Store it as CREDENTIAL_BILLOMAT_API_KEY in .env (sent as the X-BillomatApiKey header)
- Note your billomatID (the subdomain in your Billomat URL) — it forms the base URL
Environment variable: CREDENTIAL_BILLOMAT_API_KEY
One credential is needed: CREDENTIAL_BILLOMAT_API_KEY (a person-bound API key from Settings > Employees). Replace YOUR_BILLOMAT_ID in the backends.yaml url with your account subdomain. Billomat has no OAuth scopes — the API key grants the issuing user's permissions, so restrict that user to limit API access. Optional: registering an App (Settings > Administration > Apps) yields an App-ID/App-Secret sent as separate X-AppId / X-AppSecret headers that only raise the rate limit (300 → plan quota per 15 min); adding those two credential-backed headers would need a small ToolMesh auth extension. A free developer account is available from [email protected].
How do you install the Billomat MCP server with ToolMesh?
Add to your backends.yaml:
- name: billomat
transport: rest
dadl: billomat.dadl
url: "https://YOUR_BILLOMAT_ID.billomat.net/api"
Set the credential:
CREDENTIAL_BILLOMAT_API_KEY=your-token-hereWhat 145 tools does the Billomat DADL expose?
GETlist_clientsList clients (customers). Filter with name, client_number, email, country_code, note, tags, invoice_id, creditor_identifier. Returns an array of client objects (values are strings).
GETget_clientRetrieve a single client by numeric IDPOSTcreate_clientCreate a client. Wrap fields under the `client` key.
PUTupdate_clientUpdate a client. Wrap changed fields under the `client` key (same fields as create_client).DELETEdelete_clientPermanently delete a client. Fails if the client still has documents.GETlist_contactsList contacts for one client. client_id is REQUIRED — contacts are always scoped to a single client. Returns an array of contact objects.
GETget_contactRetrieve a single contact by IDPOSTcreate_contactCreate a contact for a client. Empty fields inherit the client's value.PUTupdate_contactUpdate a contact (same fields as create_contact).DELETEdelete_contactDelete a contactGETlist_articlesList catalog articles (products/services). Filter with article_number, title, description, currency_code, unit_id, supplier_id. Returns an array.
GETget_articleRetrieve a single article by IDPOSTcreate_articleCreate a catalog article.PUTupdate_articleUpdate an article (same fields as create_article).DELETEdelete_articleDelete an article from the catalogGETlist_invoicesList invoices. Filters: client_id, contact_id, invoice_number, status (DRAFT/OPEN/OVERDUE/PAID/CANCELED — comma-separated OR), payment_type, from, to (YYYY-MM-DD), label, intro, note, tags, article_id. group_by (client/status/day/week/month/year) returns aggregated sums instead. Returns an array of invoice objects (all values are strings).
GETget_invoiceRetrieve a single invoice by ID (includes combined taxes and totals)POSTcreate_invoiceCreate an invoice (always DRAFT). Line items may be embedded. Call complete_invoice afterwards to assign a number and render the PDF.
PUTupdate_invoiceUpdate an invoice. Only DRAFT invoices can be edited. Items are managed via invoice-items, not here.DELETEdelete_invoiceDelete an invoice with all its documents (PDFs), items and comments. Irreversible.PUTcomplete_invoiceComplete a DRAFT invoice: assigns the final invoice number, renders the PDF and moves the status to OPEN (or OVERDUE/PAID). Optional template_id.
POSTemail_invoiceSend the invoice to the client by e-mail. SIDE EFFECT: sends a real e-mail. recipients must contain at least one of to/cc/bcc.
PUTcancel_invoiceCancel a completed invoice (status -> CANCELED)PUTuncancel_invoiceUndo the cancellation of an invoiceGETget_invoice_pdfGet the invoice PDF metadata and content. Returns { base64file, filename, mimetype, filesize } — decode base64file to obtain the PDF bytes.
GETlist_invoice_itemsList line items of an invoice. invoice_id is required. Returns an array ordered by position.GETget_invoice_itemRetrieve a single invoice line item by IDPOSTcreate_invoice_itemAdd a line item to an existing invoice (DRAFT only).PUTupdate_invoice_itemUpdate an invoice line item (same fields as create_invoice_item, without invoice_id).DELETEdelete_invoice_itemDelete an invoice line itemGETlist_invoice_paymentsList payments booked against invoices. Filters: invoice_id, from, to, type (payment type, comma-OR), user_id. Returns an array.
GETget_invoice_paymentRetrieve a single invoice payment by IDPOSTcreate_invoice_paymentBook a payment for an invoice (invoice must be OPEN or OVERDUE). Set mark_invoice_as_paid to also flip the invoice to PAID.
DELETEdelete_invoice_paymentDelete an invoice paymentGETlist_invoice_commentsList comments/activity-log entries of an invoice. invoice_id required. Returns an array.POSTcreate_invoice_commentAdd a comment to an invoice's activity log.DELETEdelete_invoice_commentDelete an invoice commentGETlist_invoice_tagsList tags of an invoice. invoice_id required. Returns an array.POSTcreate_invoice_tagAttach a tag to an invoice.DELETEdelete_invoice_tagRemove a tag from an invoiceGETlist_recurringsList recurring invoice templates. Filters: client_id, contact_id, name, payment_type, cycle. Returns an array of recurring objects.
GETget_recurringRetrieve a single recurring invoice template by IDPOSTcreate_recurringCreate a recurring invoice template that auto-generates invoices on a cycle.PUTupdate_recurringUpdate a recurring invoice template (same fields as create_recurring).DELETEdelete_recurringDelete a recurring invoice templateGETlist_recurring_itemsList line items of a recurring template. recurring_id required. Returns an array.GETget_recurring_itemRetrieve a single recurring line item by IDPOSTcreate_recurring_itemAdd a line item to a recurring template.PUTupdate_recurring_itemUpdate a recurring line item (same fields as create_recurring_item, without recurring_id).DELETEdelete_recurring_itemDelete a recurring line itemGETlist_offersList estimates (offers/quotes). Filters: client_id, contact_id, offer_number, status (DRAFT/OPEN/WON/LOST/CANCELED/CLEARED — comma-OR), from, to, label, intro, note, tags, article_id. Returns an array.
GETget_offerRetrieve a single estimate by IDPOSTcreate_offerCreate an estimate/offer (always DRAFT). Complete it to assign a number and render the PDF.PUTupdate_offerUpdate an estimate (DRAFT only; same fields as create_offer).DELETEdelete_offerDelete an estimate with all items and commentsPUTcomplete_offerComplete a DRAFT estimate: assigns the number, renders the PDF, moves status to OPEN. Optional template_id.POSTemail_offerSend the estimate to the client by e-mail. SIDE EFFECT: sends a real e-mail.PUTcancel_offerCancel an estimate (status -> CANCELED)PUTuncancel_offerUndo the cancellation of an estimateGETget_offer_pdfGet the estimate PDF: { base64file, filename, mimetype, filesize } — decode base64file.GETlist_offer_itemsList line items of an estimate. offer_id required. Returns an array.GETget_offer_itemRetrieve a single estimate line item by IDPOSTcreate_offer_itemAdd a line item to an estimate.PUTupdate_offer_itemUpdate an estimate line item (same fields as create_offer_item, without offer_id).DELETEdelete_offer_itemDelete an estimate line itemGETlist_confirmationsList order confirmations. Filters: client_id, contact_id, confirmation_number, status (DRAFT/OPEN/CANCELED/CLEARED), from, to, label, intro, note, tags, article_id. Returns an array.
GETget_confirmationRetrieve a single order confirmation by IDPOSTcreate_confirmationCreate an order confirmation (always DRAFT).PUTupdate_confirmationUpdate an order confirmation (DRAFT only; same fields as create_confirmation).DELETEdelete_confirmationDelete an order confirmation with all items and commentsPUTcomplete_confirmationComplete a DRAFT confirmation: assigns the number, renders the PDF, moves status to OPEN.POSTemail_confirmationSend the order confirmation by e-mail. SIDE EFFECT: sends a real e-mail.PUTcancel_confirmationCancel an order confirmation (status -> CANCELED)GETget_confirmation_pdfGet the confirmation PDF: { base64file, filename, mimetype, filesize } — decode base64file.GETlist_confirmation_itemsList line items of an order confirmation. confirmation_id required. Returns an array.GETget_confirmation_itemRetrieve a single confirmation line item by IDPOSTcreate_confirmation_itemAdd a line item to an order confirmation.PUTupdate_confirmation_itemUpdate a confirmation line item (same fields as create_confirmation_item, without confirmation_id).DELETEdelete_confirmation_itemDelete a confirmation line itemGETlist_credit_notesList credit notes. Filters: client_id, contact_id, credit_note_number, status (DRAFT/OPEN/PAID/CANCELED), from, to, label, intro, note, tags, article_id, invoice_id. Returns an array.
GETget_credit_noteRetrieve a single credit note by IDPOSTcreate_credit_noteCreate a credit note (always DRAFT). Optionally reference a source invoice via invoice_id.PUTupdate_credit_noteUpdate a credit note (DRAFT only; same fields as create_credit_note).DELETEdelete_credit_noteDelete a credit note with all items and commentsPUTcomplete_credit_noteComplete a DRAFT credit note: assigns the number, renders the PDF, moves status to OPEN.POSTemail_credit_noteSend the credit note by e-mail. SIDE EFFECT: sends a real e-mail.GETget_credit_note_pdfGet the credit note PDF: { base64file, filename, mimetype, filesize } — decode base64file.GETlist_credit_note_itemsList line items of a credit note. credit_note_id required. Returns an array.GETget_credit_note_itemRetrieve a single credit note line item by IDPOSTcreate_credit_note_itemAdd a line item to a credit note.PUTupdate_credit_note_itemUpdate a credit note line item (same fields as create_credit_note_item, without credit_note_id).DELETEdelete_credit_note_itemDelete a credit note line itemGETlist_delivery_notesList delivery notes. Filters: client_id, contact_id, delivery_note_number, status (DRAFT/OPEN/CANCELED), from, to, label, intro, note, tags, article_id, invoice_id. Returns an array.
GETget_delivery_noteRetrieve a single delivery note by IDPOSTcreate_delivery_noteCreate a delivery note (always DRAFT). Often created from an invoice via invoice_id.PUTupdate_delivery_noteUpdate a delivery note (DRAFT only; same fields as create_delivery_note).DELETEdelete_delivery_noteDelete a delivery note with all items and commentsPUTcomplete_delivery_noteComplete a DRAFT delivery note: assigns the number, renders the PDF, moves status to OPEN.POSTemail_delivery_noteSend the delivery note by e-mail. SIDE EFFECT: sends a real e-mail.GETget_delivery_note_pdfGet the delivery note PDF: { base64file, filename, mimetype, filesize } — decode base64file.GETlist_delivery_note_itemsList line items of a delivery note. delivery_note_id required. Returns an array.GETget_delivery_note_itemRetrieve a single delivery note line item by IDPOSTcreate_delivery_note_itemAdd a line item to a delivery note.PUTupdate_delivery_note_itemUpdate a delivery note line item (same fields as create_delivery_note_item, without delivery_note_id).DELETEdelete_delivery_note_itemDelete a delivery note line itemGETlist_remindersList dunning reminders for overdue invoices. Filters: client_id, contact_id, invoice_id, invoice_number, status (DRAFT/OPEN/CANCELED), from, to, label, intro, note. Returns an array.
GETget_reminderRetrieve a single dunning reminder by IDPOSTcreate_reminderCreate a dunning reminder for an overdue invoice (always DRAFT). The reminder level escalates automatically based on prior reminders.
PUTupdate_reminderUpdate a dunning reminder (DRAFT only; same fields as create_reminder).DELETEdelete_reminderDelete a dunning reminderPUTcomplete_reminderComplete a DRAFT reminder: assigns the number, renders the PDF, moves status to OPEN.POSTemail_reminderSend the dunning reminder by e-mail. SIDE EFFECT: sends a real e-mail.GETget_reminder_pdfGet the reminder PDF: { base64file, filename, mimetype, filesize } — decode base64file.GETlist_suppliersList suppliers. Filters: name, supplier_number, email, country_code, note, tags. Returns an array.GETget_supplierRetrieve a single supplier by IDPOSTcreate_supplierCreate a supplier (vendor for incoming invoices).PUTupdate_supplierUpdate a supplier (same fields as create_supplier).DELETEdelete_supplierDelete a supplierGETlist_incomingsList incoming invoices (expenses / supplier bills). Filters: supplier_id, number, status (paid/unpaid/overdue), from, to, tags. Returns an array.
GETget_incomingRetrieve a single incoming invoice by IDPOSTcreate_incomingRecord an incoming invoice (expense) from a supplier.PUTupdate_incomingUpdate an incoming invoice (same fields as create_incoming).DELETEdelete_incomingDelete an incoming invoiceGETlist_incoming_paymentsList payments made against incoming invoices. Filter with incoming_id. Returns an array.POSTcreate_incoming_paymentBook a payment against an incoming invoice.DELETEdelete_incoming_paymentDelete an incoming paymentGETlist_taxesList configured tax rates. Returns an array of tax objects (name, rate, is_default).GETget_taxRetrieve a single tax rate by IDPOSTcreate_taxCreate a tax rate.PUTupdate_taxUpdate a tax rate (same fields as create_tax).DELETEdelete_taxDelete a tax rateGETlist_unitsList units of measure (e.g. hour, piece). Returns an array of unit objects.GETget_unitRetrieve a single unit by IDPOSTcreate_unitCreate a unit of measure.PUTupdate_unitRename a unit of measure.DELETEdelete_unitDelete a unit of measureGETlist_templatesList document (PDF) templates. Filter with type (INVOICE, OFFER, ...). Returns an array.GETget_templateRetrieve a single document template by IDGETlist_email_templatesList e-mail templates used by the email_* actions. Returns an array.GETget_email_templateRetrieve a single e-mail template by IDGETget_settingsRetrieve the account settings (default number ranges, texts, due days, currency, tax defaults, etc.).GETlist_usersList employees/users of the account. Returns an array of user objects.GETget_userRetrieve a single user by IDGETlist_countriesList countries with their tax/currency configuration. Returns an array.GETlist_currenciesList configured currencies. Returns an array.