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?
GET list_clients List 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).
GET get_client Retrieve a single client by numeric ID POST create_client Create a client. Wrap fields under the `client` key.
PUT update_client Update a client. Wrap changed fields under the `client` key (same fields as create_client). DELETE delete_client Permanently delete a client. Fails if the client still has documents. GET list_contacts List contacts for one client. client_id is REQUIRED — contacts are always scoped to a single client. Returns an array of contact objects.
GET get_contact Retrieve a single contact by ID POST create_contact Create a contact for a client. Empty fields inherit the client's value. PUT update_contact Update a contact (same fields as create_contact). DELETE delete_contact Delete a contact GET list_articles List catalog articles (products/services). Filter with article_number, title, description, currency_code, unit_id, supplier_id. Returns an array.
GET get_article Retrieve a single article by ID POST create_article Create a catalog article. PUT update_article Update an article (same fields as create_article). DELETE delete_article Delete an article from the catalog GET list_invoices List 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).
GET get_invoice Retrieve a single invoice by ID (includes combined taxes and totals) POST create_invoice Create an invoice (always DRAFT). Line items may be embedded. Call complete_invoice afterwards to assign a number and render the PDF.
PUT update_invoice Update an invoice. Only DRAFT invoices can be edited. Items are managed via invoice-items, not here. DELETE delete_invoice Delete an invoice with all its documents (PDFs), items and comments. Irreversible. PUT complete_invoice Complete a DRAFT invoice: assigns the final invoice number, renders the PDF and moves the status to OPEN (or OVERDUE/PAID). Optional template_id.
POST email_invoice Send 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.
PUT cancel_invoice Cancel a completed invoice (status -> CANCELED) PUT uncancel_invoice Undo the cancellation of an invoice GET get_invoice_pdf Get the invoice PDF metadata and content. Returns { base64file, filename, mimetype, filesize } — decode base64file to obtain the PDF bytes.
GET list_invoice_items List line items of an invoice. invoice_id is required. Returns an array ordered by position. GET get_invoice_item Retrieve a single invoice line item by ID POST create_invoice_item Add a line item to an existing invoice (DRAFT only). PUT update_invoice_item Update an invoice line item (same fields as create_invoice_item, without invoice_id). DELETE delete_invoice_item Delete an invoice line item GET list_invoice_payments List payments booked against invoices. Filters: invoice_id, from, to, type (payment type, comma-OR), user_id. Returns an array.
GET get_invoice_payment Retrieve a single invoice payment by ID POST create_invoice_payment Book a payment for an invoice (invoice must be OPEN or OVERDUE). Set mark_invoice_as_paid to also flip the invoice to PAID.
DELETE delete_invoice_payment Delete an invoice payment GET list_invoice_comments List comments/activity-log entries of an invoice. invoice_id required. Returns an array. POST create_invoice_comment Add a comment to an invoice's activity log. DELETE delete_invoice_comment Delete an invoice comment GET list_invoice_tags List tags of an invoice. invoice_id required. Returns an array. POST create_invoice_tag Attach a tag to an invoice. DELETE delete_invoice_tag Remove a tag from an invoice GET list_recurrings List recurring invoice templates. Filters: client_id, contact_id, name, payment_type, cycle. Returns an array of recurring objects.
GET get_recurring Retrieve a single recurring invoice template by ID POST create_recurring Create a recurring invoice template that auto-generates invoices on a cycle. PUT update_recurring Update a recurring invoice template (same fields as create_recurring). DELETE delete_recurring Delete a recurring invoice template GET list_recurring_items List line items of a recurring template. recurring_id required. Returns an array. GET get_recurring_item Retrieve a single recurring line item by ID POST create_recurring_item Add a line item to a recurring template. PUT update_recurring_item Update a recurring line item (same fields as create_recurring_item, without recurring_id). DELETE delete_recurring_item Delete a recurring line item GET list_offers List 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.
GET get_offer Retrieve a single estimate by ID POST create_offer Create an estimate/offer (always DRAFT). Complete it to assign a number and render the PDF. PUT update_offer Update an estimate (DRAFT only; same fields as create_offer). DELETE delete_offer Delete an estimate with all items and comments PUT complete_offer Complete a DRAFT estimate: assigns the number, renders the PDF, moves status to OPEN. Optional template_id. POST email_offer Send the estimate to the client by e-mail. SIDE EFFECT: sends a real e-mail. PUT cancel_offer Cancel an estimate (status -> CANCELED) PUT uncancel_offer Undo the cancellation of an estimate GET get_offer_pdf Get the estimate PDF: { base64file, filename, mimetype, filesize } — decode base64file. GET list_offer_items List line items of an estimate. offer_id required. Returns an array. GET get_offer_item Retrieve a single estimate line item by ID POST create_offer_item Add a line item to an estimate. PUT update_offer_item Update an estimate line item (same fields as create_offer_item, without offer_id). DELETE delete_offer_item Delete an estimate line item GET list_confirmations List 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.
GET get_confirmation Retrieve a single order confirmation by ID POST create_confirmation Create an order confirmation (always DRAFT). PUT update_confirmation Update an order confirmation (DRAFT only; same fields as create_confirmation). DELETE delete_confirmation Delete an order confirmation with all items and comments PUT complete_confirmation Complete a DRAFT confirmation: assigns the number, renders the PDF, moves status to OPEN. POST email_confirmation Send the order confirmation by e-mail. SIDE EFFECT: sends a real e-mail. PUT cancel_confirmation Cancel an order confirmation (status -> CANCELED) GET get_confirmation_pdf Get the confirmation PDF: { base64file, filename, mimetype, filesize } — decode base64file. GET list_confirmation_items List line items of an order confirmation. confirmation_id required. Returns an array. GET get_confirmation_item Retrieve a single confirmation line item by ID POST create_confirmation_item Add a line item to an order confirmation. PUT update_confirmation_item Update a confirmation line item (same fields as create_confirmation_item, without confirmation_id). DELETE delete_confirmation_item Delete a confirmation line item GET list_credit_notes List 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.
GET get_credit_note Retrieve a single credit note by ID POST create_credit_note Create a credit note (always DRAFT). Optionally reference a source invoice via invoice_id. PUT update_credit_note Update a credit note (DRAFT only; same fields as create_credit_note). DELETE delete_credit_note Delete a credit note with all items and comments PUT complete_credit_note Complete a DRAFT credit note: assigns the number, renders the PDF, moves status to OPEN. POST email_credit_note Send the credit note by e-mail. SIDE EFFECT: sends a real e-mail. GET get_credit_note_pdf Get the credit note PDF: { base64file, filename, mimetype, filesize } — decode base64file. GET list_credit_note_items List line items of a credit note. credit_note_id required. Returns an array. GET get_credit_note_item Retrieve a single credit note line item by ID POST create_credit_note_item Add a line item to a credit note. PUT update_credit_note_item Update a credit note line item (same fields as create_credit_note_item, without credit_note_id). DELETE delete_credit_note_item Delete a credit note line item GET list_delivery_notes List 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.
GET get_delivery_note Retrieve a single delivery note by ID POST create_delivery_note Create a delivery note (always DRAFT). Often created from an invoice via invoice_id. PUT update_delivery_note Update a delivery note (DRAFT only; same fields as create_delivery_note). DELETE delete_delivery_note Delete a delivery note with all items and comments PUT complete_delivery_note Complete a DRAFT delivery note: assigns the number, renders the PDF, moves status to OPEN. POST email_delivery_note Send the delivery note by e-mail. SIDE EFFECT: sends a real e-mail. GET get_delivery_note_pdf Get the delivery note PDF: { base64file, filename, mimetype, filesize } — decode base64file. GET list_delivery_note_items List line items of a delivery note. delivery_note_id required. Returns an array. GET get_delivery_note_item Retrieve a single delivery note line item by ID POST create_delivery_note_item Add a line item to a delivery note. PUT update_delivery_note_item Update a delivery note line item (same fields as create_delivery_note_item, without delivery_note_id). DELETE delete_delivery_note_item Delete a delivery note line item GET list_reminders List 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.
GET get_reminder Retrieve a single dunning reminder by ID POST create_reminder Create a dunning reminder for an overdue invoice (always DRAFT). The reminder level escalates automatically based on prior reminders.
PUT update_reminder Update a dunning reminder (DRAFT only; same fields as create_reminder). DELETE delete_reminder Delete a dunning reminder PUT complete_reminder Complete a DRAFT reminder: assigns the number, renders the PDF, moves status to OPEN. POST email_reminder Send the dunning reminder by e-mail. SIDE EFFECT: sends a real e-mail. GET get_reminder_pdf Get the reminder PDF: { base64file, filename, mimetype, filesize } — decode base64file. GET list_suppliers List suppliers. Filters: name, supplier_number, email, country_code, note, tags. Returns an array. GET get_supplier Retrieve a single supplier by ID POST create_supplier Create a supplier (vendor for incoming invoices). PUT update_supplier Update a supplier (same fields as create_supplier). DELETE delete_supplier Delete a supplier GET list_incomings List incoming invoices (expenses / supplier bills). Filters: supplier_id, number, status (paid/unpaid/overdue), from, to, tags. Returns an array.
GET get_incoming Retrieve a single incoming invoice by ID POST create_incoming Record an incoming invoice (expense) from a supplier. PUT update_incoming Update an incoming invoice (same fields as create_incoming). DELETE delete_incoming Delete an incoming invoice GET list_incoming_payments List payments made against incoming invoices. Filter with incoming_id. Returns an array. POST create_incoming_payment Book a payment against an incoming invoice. DELETE delete_incoming_payment Delete an incoming payment GET list_taxes List configured tax rates. Returns an array of tax objects (name, rate, is_default). GET get_tax Retrieve a single tax rate by ID POST create_tax Create a tax rate. PUT update_tax Update a tax rate (same fields as create_tax). DELETE delete_tax Delete a tax rate GET list_units List units of measure (e.g. hour, piece). Returns an array of unit objects. GET get_unit Retrieve a single unit by ID POST create_unit Create a unit of measure. PUT update_unit Rename a unit of measure. DELETE delete_unit Delete a unit of measure GET list_templates List document (PDF) templates. Filter with type (INVOICE, OFFER, ...). Returns an array. GET get_template Retrieve a single document template by ID GET list_email_templates List e-mail templates used by the email_* actions. Returns an array. GET get_email_template Retrieve a single e-mail template by ID GET get_settings Retrieve the account settings (default number ranges, texts, due days, currency, tax defaults, etc.). GET list_users List employees/users of the account. Returns an array of user objects. GET get_user Retrieve a single user by ID GET list_countries List countries with their tax/currency configuration. Returns an array. GET list_currencies List configured currencies. Returns an array.