Buchhaltungsbutler MCP

Receipts: upload receipt

receipts_upload

Upload a receipt file for automatic document recognition and bookkeeping. Sends the file to BuchhaltungsButler, which processes it and returns the stored filename.

Instructions

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

upload receipt

Upload a receipt into the specified customer account. The receipt will be processed by the BuchhaltungsButler technology. The response includes the filename (without extension) of the receipt as it is stored.

Note: max 10 requests per minute

Use to send the actual receipt file. BuchhaltungsButler runs document recognition on it and returns the stored filename.

To record a receipt without a file, use receipts_create.

Rate limited to 10 requests per minute. Not idempotent, so uploading the same file twice creates two receipts.

Endpoint: POST /receipts/upload

Input Schema

TableJSON Schema

Name	Required	Description
`date`	No	The receipt's issuing date in format 'YYYY-MM-DD' (e.g. '2017-04-26'). If specified, the field will be validated. An empty string is not considered a valid date. NOTE: This parameter will be ignored when you upload an e-invoice!
`file`	Yes	The receipt file as real file upload or as base64 encoded string. Accepted file types are: application/pdf, text/xml, application/xml, image/jpeg, image/png, image/bmp, image/tiff
`type`	Yes	Can be 'invoice inbound' ("Eingangsrechnung"), 'invoice outbound' ("Ausgangsrechnung"), 'credit inbound' ("Eingangsgutschrift § 14 UStG"), 'credit outbound' ("Ausgangsgutschrift § 14 UStG").
`amount`	No	The total amount of the receipt, can be negative to indicate a reversed payment (e.g. -12.30). If specified, the field will be validated. '0.00' is not considered a valid receipt amount. NOTE: This parameter will be ignored when you upload an e-invoice!
`account`	No	If the receipt shall directly be assigned to a payment account, you can specify its posting account number (e.g. '1200'). If specified, the account must exist as a payment account for the customer. '0' is not considered a valid account.
`currency`	No	Has to be 'EUR' if specified. If specified, the field will be validated. An empty string is not considered a valid currency. NOTE: This parameter will be ignored when you upload an e-invoice!
`vat_rate`	No	The receipt's vat rate (e.g. 19.00 or 0) - may also be an empty string to indicate a non-available or multiple vat rates. NOTE: This parameter will be ignored when you upload an e-invoice!
`file_name`	No	The name of the file. NOTE: This is required for files sent as base64 encoded string and will be ignored for files sent as real upload.
`counterparty`	No	The counterparty of the receipt, i.e. the invoicing party for type 'invoice inbound' or the recipient for type 'invoice outbound' (e.g. 'Peter Maier'). If specified, the field will be validated. An empty string is not considered a valid counterparty. NOTE: This parameter will be ignored when you upload an e-invoice!
`date_delivery`	No	The delivery date in format 'YYYY-MM-DD' (e.g. '2017-04-26'). NOTE: Due to the DATEV compatibility, we cannot accept a delivery date that is after the receipt date! If specified, it will be validated. NOTE: This parameter will be ignored when you upload an e-invoice!
`invoice_number`	No	The invoice number (e.g. '1231XU23') with a maximum length of 60 characters - may also be an empty string. NOTE: This parameter will be ignored when you upload an e-invoice!
`creditor_debtor`	No	If the receipt shall directly be assigned to a creditor (for type 'invoice inbound') or debtor (for type 'invoice outbound') account, you can specify its posting account number (e.g. '70001'). If specified, creditors/debtors have to be activated for the customer, the creditor/debtor account must exist for the customer and it must be compatible with the specified receipt type. '0' is not considered a valid creditor/debtor.
`date_payment_due`	No	The payment due date in format 'YYYY-MM-DD' (e.g. '2017-04-26'). NOTE: This parameter will be ignored when you upload an e-invoice!
`payment_reference`	No	The payment reference id. If specified correctly, the uploaded receipt will match with the corresponding transaction. Currently we support Amazon order id, PayPal transaction id and Stripe transaction id. NOTE: This parameter will be ignored when you upload an e-invoice!
`link_to_receipt_id_by_customer`	No	Has to be a valid id_by_customer of another receipt. If specified, both receipts will be assigned to a transaction if one of them is assigned manually.

Output Schema

TableJSON Schema

Name	Required	Description
`message`	No	blank
`success`	Yes	Success boolean
`filename`	No	Internal filename after upload without extension
`id_by_customer`	No	blank

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.1.2Sep 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "filename": {
+      "description": "Internal filename after upload without extension",
+      "type": "string"
+    },
+    "id_by_customer": {
+      "description": "blank",
+      "type": "string"
+    },
+    "message": {
+      "description": "blank",
+      "type": "string"
+    },
+    "success": {
+      "description": "Success boolean",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "success"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv1.1.0Sep 9, 2026

removedInput schema / properties / api_key

Removed value: -{
-  "description": "Optional. The BB customer api_key to act on. Defaults to the BB_API_KEY configured on the server — only set this to target a different customer.",
-  "type": "string"
-}

First observedv1.0.0Jul 29, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses non-idempotency ('calling twice may create duplicates') and rate limiting ('max 10 requests per minute'), which are behavioral traits not fully covered by annotations alone. It also explains the processing via BuchhaltungsButler and the response filename, adding valuable context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description contains redundancy: 'Not idempotent' appears twice and 'Rate limited to 10 requests per minute' also appears twice. The inclusion of the 'Endpoint: POST /receipts/upload' line is unnecessary as it is not behaviorally relevant. While structured, the repetition prevents a higher score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 15 parameters and an output schema, the description covers the primary purpose, alternatives, rate limit, non-idempotency, and the response format (filename). The schema handles parameter details, so the description is sufficiently complete for an agent to decide when and how to invoke the tool. Minor gaps like e-invoice behavior are covered in the schema, so a 4 is justified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are already documented in the schema. The description does not add any parameter-specific semantics beyond what the schema provides; it only offers general notes about rate limiting and non-idempotency. Thus, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Upload a receipt into the specified customer account' and clearly identifies the resource and action. It also differentiates from the sibling tool receipts_create by noting 'To record a receipt without a file, use receipts_create', making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use it ('Use to send the actual receipt file') and when not to ('To record a receipt without a file, use receipts_create'). It also mentions the rate limit and non-idempotency, giving clear context for usage decisions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server