Search for an existing customer by company name, person name, email, customer number or city.

USE THIS FIRST whenever you need to know whether someone is already a customer — for example before creating an offer or invoice from an inbound inquiry. The easybill API has no full-text search, so this tool combines exact filters with a local fuzzy match over the customer list.

It tolerates the differences that break exact matching: legal forms ('GmbH & Co. KG'), punctuation ('M.B. MUSTERMANN' vs 'MB Mustermann'), umlauts, and word order.

Args:

• query (string): what to search for. A company name, surname, email or customer number.

• limit (number): max candidates to return, 1-25 (default 5).

• min_score (number): 0-1 match threshold (default 0.5). Lower it to cast a wider net.

• max_pages (number): how many pages of 1000 customers to scan in the fallback (default 3). Each page is one API request, so keep this low on a plan with a 10 req/min limit.

Returns: { query, match_count, exact_match (boolean), candidates[] } where each candidate has its easybill 'id', 'match_score' (1 = certain) and the usual summary fields.

Next steps based on the result:

• Exactly one strong candidate (score 1) -> use its 'id' as customer_id.

• Several candidates -> show them to the user and ask which one, do NOT guess.

• No candidates -> the customer does not exist yet. Create it with easybill_create_customer, then use the returned 'id'.

Examples:

• "Is Mustermann Handels GmbH & Co. KG already a customer?" -> query="Mustermann Handels GmbH & Co. KG"

• "Find the customer with email einkauf@example.com" -> query="einkauf@example.com"

• "Look up customer number 10023" -> query="10023"

List customers from easybill with optional filters and pagination.

NOTE: easybill has no fuzzy full-text customer search. The filters below match exact values (though each accepts several comma-separated values). To find a customer by a partial name, filter on company_name or last_name with the exact spelling, or page through the list and match locally.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one customer by its numeric easybill ID, returning all fields by default.

Use easybill_list_customers first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List contacts from easybill with optional filters and pagination.

Contacts are always scoped to one customer, so 'customer_id' is required.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one contact by its numeric easybill ID, returning all fields by default.

Use easybill_list_contacts first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List customer groups from easybill with optional filters and pagination.

Customer groups classify customers and can carry their own pricing level. Use a group's 'id' as 'group_id' when creating or filtering customers.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one customer group by its numeric easybill ID, returning all fields by default.

Use easybill_list_customer_groups first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List documents from easybill with optional filters and pagination.

Covers every document type: invoices, offers, credit notes, reminders, deliveries, orders.

NOT the right tool for: finding out whether a customer exists (use easybill_find_customer), or orienting yourself before creating a document (see easybill_create_document). Only call this when you actually need to read existing documents, and always with a filter.

Common recipes:

• Unpaid invoices: type='INVOICE', paid_at='null'

• Revenue in a period: type='INVOICE', document_date='2025-01-01,2025-12-31'

• A customer's history: customer_id=

• Exclude drafts: is_draft='0' - exclude cancelled: cancel_id='null'

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one document by its numeric easybill ID, returning all fields by default.

Use easybill_list_documents first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Download a document as a PDF or e-invoicing file and save it to a local path.

Supported formats: 'pdf' (plain), 'zugferd1', 'zugferd2_2' (PDF with embedded XML), 'xrechnung2_3', 'xrechnung3_0' (XML), and 'jpg' (first page as an image).

Returns the saved file path and its size in bytes. The file content itself is NOT loaded into the conversation, so this is safe for large PDFs.

List the change history of a document. easybill snapshots a version whenever a completed document is modified, which is what you need for audit questions like 'was this invoice altered after it was issued?'.

Returns: { total, count, page, pages, items[] } with each version's id, created_at and reason.

List positions from easybill with optional filters and pagination.

Positions are the reusable article catalogue (products, services and text blocks). Referencing one by 'position_id' in a document line item copies its price and description over. Prices are integers in cents (1999 = 19.99 EUR).

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one position by its numeric easybill ID, returning all fields by default.

Use easybill_list_positions first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List stock entries from easybill with optional filters and pagination.

Stock entries are the inventory movement log for articles that have stock management enabled (position.stock = 'YES'). Each entry records a new absolute stock level. Filter by position_id to see one article's history.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one stock entry by its numeric easybill ID, returning all fields by default.

Use easybill_list_stock_entries first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List document payments from easybill with optional filters and pagination.

Payments booked against documents. Recording a payment is what marks an invoice as paid — it updates the document's 'paid_amount' and 'paid_at'. To find open invoices instead, use easybill_list_documents with type='INVOICE' and paid_at='null'. Amounts are integers in cents (150 = 1.50 EUR).

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one document payment by its numeric easybill ID, returning all fields by default.

Use easybill_list_document_payments first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List projects from easybill with optional filters and pagination.

Projects group documents and tracked time under a customer engagement, with an optional budget. 'consumed_amount' and 'consumed_time' show progress against 'budget_amount' and 'budget_time' — useful for budget-burn questions. Amounts are integers in cents; times are in minutes.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one project by its numeric easybill ID, returning all fields by default.

Use easybill_list_projects first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List time tracking entries from easybill with optional filters and pagination.

Tracked working time, optionally tied to a project and an article. 'timer_value' is the tracked duration in MINUTES and 'hourly_rate' is in cents. 'cleared_at' is set once the entry has been billed — entries with cleared_at = null are still unbilled, which is what you want when preparing an invoice.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one time tracking entry by its numeric easybill ID, returning all fields by default.

Use easybill_list_time_trackings first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List attachments from easybill with optional filters and pagination.

Files stored in easybill and linked to a document, customer or project. This endpoint has no filters — page through the list and match on 'document_id', 'customer_id' or 'file_name'. Use easybill_download_attachment to fetch the actual file content.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one attachment by its numeric easybill ID, returning all fields by default.

Use easybill_list_attachments first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Download an attachment's file content and save it to a local path.

Returns the saved file path and size in bytes. The content is NOT loaded into the conversation, so this is safe for large files. Find attachment IDs with easybill_list_attachments.

List text templates from easybill with optional filters and pagination.

Reusable text blocks for document headers, footers and notes. Handy for reusing your standard payment terms or closing wording when creating a document.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Fetch one text template by its numeric easybill ID, returning all fields by default.

Use easybill_list_text_templates first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

List the PDF layout templates configured in your easybill account.

Pass a template's 'id' as 'pdf_template' when creating or converting a document to control its layout and language. The built-in values are 'DE' (German, the default) and 'EN' (English); anything custom uses a numeric ID.

Note: this endpoint is not paginated and returns all templates at once.

Report this MCP server's configuration and verify the easybill API credentials work.

Call this when a write tool appears to be missing, when you get authentication errors, or when you hit rate limits — it explains the current mode and limits.

Returns: { server_version, api_base_url, writes_enabled, tools_registered, rate_limit_per_minute, character_limit, connection } where 'connection' reports whether a live test call to easybill succeeded.