Benethos Lexware Office

Unofficial Lexware Office MCP Server

Disclaimer

• This project is not affiliated with, endorsed by, or sponsored by Lexware or Haufe-Lexware GmbH & Co. KG. "Lexware" and "Lexware Office" are trademarks of their respective owners.
• It uses the documented public API with an API key you generate and can revoke yourself. Use of that API is governed by Lexware's own terms, which you accept independently of this project. The API can change at any time, and requests may be rate limited or blocked.
• It reaches real accounting records. Write access is off by default. If you enable it, anything created through the API is a real and legally relevant record — a finalized document cannot be withdrawn through the API.
• Data may be incomplete or out of date. Nothing here is tax, accounting or legal advice. Do not rely on it for filings, audits, or your bookkeeping obligations.
• Provided "as is", without warranty. Intended for personal and professional use at your own risk. See LICENSE.
• For commercial use, review Lexware's API terms and your own retention and documentation duties.

Contents

• Why this exists
• Safety first
• How it works
• Tools
• Requirements
• Getting an API key
• Installation
  • As a Claude Desktop extension
  • With uvx, for any MCP client
• Configuring it in a browser
• Switching individual tools off
• Configuration
  • Where a value comes from, and which one wins
  • Naming the files
  • The settings
• Transport
• In a container
  • With Compose
  • As single containers
  • Turn the interface off when you are done
• Logs
• Example prompts
• Rate limits
• Development
• License
• Trademarks and affiliation

An MCP server that connects an MCP client such as Claude Desktop to a Lexware Office account through the official public REST API. Ask about invoices, contacts, articles and vouchers in plain language, and let the client fetch them for you.

Status: 0.6.2. The server handles contacts, vouchers and documents: find them, read them, create them, change them, see what is still unpaid, download a PDF and upload a receipt and book it. get_profile answers which account is connected. Every tool in the table below is built, and each was exercised against a live account. It speaks stdio to a client that starts it, as a Claude Desktop extension or from PyPI, and streamable HTTP behind a bearer token where something else has to reach it - as a published container image, with Compose files for running it and for building it from a checkout. See SPECS.md for the full technical specification and the roadmap.

Why this exists

Lexware Office holds the day-to-day accounting of a small business. Most questions about it are read questions — what is still unpaid, what did this customer order, which receipt belongs to that expense — and those are exactly the questions an assistant answers well once it can see the data. This server makes that possible without exporting anything, using an API key the account owner generates and can revoke.

Safety first

The server points at a real accounting system, so the defaults are cautious.

Run it read-only unless you have a reason not to. This server can change real accounting records - create a contact, record a voucher, issue an invoice, attach a receipt - and it is the assistant that decides when to call such a tool, not you. --tools read-only gives it everything it needs to answer questions about the books, which is what most people want it for: search, read, and download. Nothing in that set writes.

Turn a write tool on when you have a job for it, and know what it leaves behind. This API cannot delete a bookkeeping voucher at all, so a wrong one is corrected in the web app rather than withdrawn here, and a finalized invoice is a real document with a number that has been used. If you are not sure which tools you need, read-only is the honest starting point - the permissions page adds one later in a click, and a client that honours notifications/tools/list_changed, as Claude Desktop does, picks it up without a restart.

• Nothing is enabled until you say so. A fresh installation has no policy file, and a server without one offers no tools at all. What this server may do is a decision somebody made, never a default that happened.
• One flag per tool, in a JSON file you write with --tools, tick through setup, or edit by hand. Not a level, not a group: create_contact on and upload_file off is an ordinary thing to want, and there is no combination the file cannot express.
• What a tool costs you is visible while you decide. Every enabled tool is sent to the assistant on every request, and the permissions page puts that number on each row.
• The file is checked twice, once when the tool list is built and again when a call arrives, so a stale tool list on the client cannot slip past it.
• The API key is never logged, never returned in a tool result, and redacted from error messages. It belongs in the .env and nowhere else — not in your client's configuration file, which another program owns and rewrites, and which is the one people screenshot when they ask for help. Nor does any path from your machine reach the assistant.

How it works

The client starts the server, or reaches it over HTTP, and speaks MCP with it. What a model can do is settled before anything reaches Lexware: a tool the policy file does not name does not exist for the client, and every call that is left goes through one API client with one rate limiter. The key and the permissions live in two files that setup writes, a process of its own that the client's prompt Set up Lexware Office starts, and so does benethos-lexware-office-mcp setup in a terminal.

Tools

Every tool below is built and was exercised against a live account. None of them is enabled until the policy file names it.

Read tools:

Write tools. These change real accounting records, so enable them one at a time and against an account you are willing to have changed:

update_contact and update_voucher cost two API calls rather than one. The API replaces a record instead of patching it, so the current one is read first and the change is laid on top. Without that, changing only an email address would empty out the addresses, the note and everything else. Both also need the version you last read: if the record changed in between, the update is refused and nothing is written.

One tool deletes, and it is the only one:

It is the only member of the --tools irreversible step so far, so that step is the only way to switch it on. An article is also the only thing this API lets you delete, which is the other half of the point:

--tools write is not the same as undoable. Nothing that preset enables deletes a record, but five of its tools create one this API cannot remove afterwards: create_contact, whose contact only the web app deletes, and create_voucher, create_sales_document, upload_file and attach_file_to_voucher, which leave a bookkeeping record.

A bookkeeping voucher cannot be deleted through the API. There is no endpoint for it, so a wrong create_voucher has to be corrected in the Lexware Office web app, and it is booked the moment it is created - the API accepts no status on the way in. The same applies to upload_file: uploading a receipt also creates the voucher that goes with it, so it leaves a record behind even though its name only mentions the file. That voucher starts unchecked, and update_voucher fills it in and, when you ask for it, books it.

Downloads are written into the download directory on the machine the server runs on, and reported two ways: a path, which is what you want when the client and the server share that machine, and a resource URI, which the client can read to get the bytes wherever the server is. The file itself never travels inside the tool result, because base64 costs roughly 1.37 times the file size in context and no model can read a PDF anyway. An existing file is never replaced: a download identical to one already there reuses it, and one that differs is saved beside it with a counter in its name.

The download directory is a cache of the last 100 documents. Older downloads are deleted when the server starts and after each download, since every document is still in Lexware Office and one call away. LXO_MCP_KEPT_DOWNLOADS changes the number, and 0 keeps everything. A directory you name yourself with LXO_MCP_DOWNLOAD_DIR is left alone unless you set it there too, and even then only files named the way a download is named are deleted: a space, an umlaut or an extension such as .docx keeps a file out of it. The resource list is read from the directory each time a client asks, names the same newest downloads, and survives a restart. A new download is announced the way a changed tool list is: the server sends notifications/resources/list_changed, so a client that listed the downloads once can ask again rather than keep the list from the start of its session. Whether it does is the client's business.

The resource list is not part of the prompt. The tool list goes to the model with every request. The resource list is sent only when a client asks for it, and what the client does with it is up to the client. Claude Desktop offers it in its attachment menu, under Add from the server, and a file reaches the conversation when somebody picks it. A client that hands the whole list to the model pays for it instead: an entry carries the lexware:// URI, the file name, the type and the size - never a path of this machine - and comes to about 230 characters, so the default 100 make roughly 23,000, around 6,000 to 7,000 tokens. For such a client, set LXO_MCP_KEPT_DOWNLOADS lower, which shortens the list and the cache together.

Claude Desktop does not follow a resource link at all, so read_download is the route that always works. It takes the same URI and puts the content into the answer. What arrives depends on the file:

A PDF is rendered rather than passed through because Claude Desktop turns an embedded binary into an image block when it calls the API, and application/pdf is not a permitted image type there, so the whole request is refused. Rendering costs no API call either, since the file is already on the server.

A link into the web app is a separate tool. get_deeplink turns an id into a URL for a browser, costs no API call, and is the route that still works when the client can display neither the file nor a resource link: somebody opens it themselves. A download does not carry one — it answers where the bytes are, which is a different question, and the two were joined once long enough for a broken link to ride along with a working download.

upload_file and attach_file_to_voucher take a source: a path on the machine the server runs on, or a URL to fetch the file from. Either way they accept PDF, JPEG, PNG and XML, at most 5 MiB per file, which is what the API takes. An XML file is treated as an XRechnung and is rejected if it is not one.

The model chooses the path. Without LXO_MCP_UPLOAD_DIR, upload_file and attach_file_to_voucher read any file this process can read that has one of those extensions, and send it to Lexware. That includes any .xml: a configuration file or an export is refused as not an XRechnung only after it has reached the API. Set it to one directory - an inbox for receipts - and nothing outside it is read, links included.

A URL only from addresses you allow. Another server can hand the model a short-lived link to a file - a mailbox server for an attachment, say - and the file then goes from that server to Lexware without passing through the model. LXO_MCP_UPLOAD_URLS lists the addresses such a link may point to, comma separated: a scheme and a host, optionally a port and the start of a path, such as https://files.example.com/inbox/. Without it no URL is fetched. The list is required because the model chooses the URL, and a model reads email: one instruction hidden in a message could otherwise have the server fetch from anywhere it can reach, a document server on your own network included, and file what came back in your books. A link outside every prefix is refused before anything is sent, a redirect is not followed, the fetch gets 30 seconds, and the file is cut off at 5 MiB. It is asked for uncompressed, an empty file is refused, and behind a proxy a service on this machine is fetched directly, since the proxy cannot reach it. A file served only as bytes, application/octet-stream or without a type, as a mail attachment often is, is taken by its first bytes, and only as one of the four types. The Lexware key is never sent along, and the log names a link's host, never its path or query, which is where a signed link keeps its key.

Each entry is a URL prefix, not a pattern. A link is fetched when it starts with one: the same scheme, exactly the same host, the same port - none given means 443 for https and 80 for http - and a path at or below the prefix's. What follows is free, the rest of the path and the query a signed link carries. With https://files.example.com/inbox/:

• https://files.example.com/inbox/9f3c?sig=abc is fetched
• https://files.example.com/outbox/9f3c is not, another path
• https://files.example.com.elsewhere.net/inbox/9f3c is not, another host
• https://files.example.com:8443/inbox/9f3c is not, another port

https://files.example.com/ allows every path on that host. There is no wildcard: a host is always written out in full, and a * is read as a host name that nothing is called, so https://* allows nothing at all.

https:// is the rule. http:// is meant for a service on the same machine, and is accepted for 127.0.0.1, ::1 and localhost alone: the server refuses to start with any other host, since the file would cross the network unencrypted. In a container, the same machine is the container.

Requirements

• uv, which brings its own Python and the uvx command every example below uses. The Claude Desktop extension needs neither uv nor Python: Claude Desktop brings both
• Python 3.11 or newer, if you would rather bring your own. Installing pulls in the MCP SDK, httpx, platformdirs, pypdfium2 to render PDF pages, and Jinja2 for the pages of setup
• A Lexware Office account with the public API add-on enabled
• An API key from https://app.lexware.de/addons/public-api

Getting an API key

1. Sign in to Lexware Office as the account owner.
2. Open the public API add-on at https://app.lexware.de/addons/public-api.
3. Create a key and copy it once — it is shown a single time.
4. Keep it out of any file that goes into version control. setup writes it into the .env the server reads, in the per-user configuration directory or, in a checkout, in config/.env, which is gitignored. Either is found no matter which directory the server is started from, so a client such as Claude Desktop needs no key of its own in its configuration file. An environment variable works as well.

A key can be revoked on the same page at any time, which is the fastest way to cut access if anything looks wrong.

Installation

Two ways in. In Claude Desktop the shortest is the extension, which needs nothing installed beside Claude Desktop. For any other client, or to manage the server yourself, run it with uvx. Both read the same configuration, so moving from one to the other keeps the key and the permissions. To run it in a container instead, see In a container.

The server is also listed in the official MCP Registry as io.github.benethos-hub/benethos-lexware-office-mcp, with all three: the PyPI package, the container image and the extension.

As a Claude Desktop extension

All it needs is Claude Desktop, signed in.

1. Get an API key. Sign in to Lexware Office as the account owner, open https://app.lexware.de/addons/public-api, create a key and copy it straight away, as it is shown once only. The same page revokes it at any time. See Getting an API key.

2. Download the extension. This link always gives the newest release: benethos-lexware-office-mcp.mcpb.

3. Drag it into Claude Desktop under Settings → Extensions. Claude Desktop brings Python and uv itself, nothing else has to be installed.

4. Open the setup. In a chat, click the plus in the message box, then Connectors → Add from Unofficial Lexware Office MCP Server → Set up Lexware Office. Your browser opens the interface described under Configuring it in a browser. Only you can pick this, the model cannot.

5. Enter the key and choose the tools. The key goes under Zugangsdaten, the tools are ticked under Rechte, and Beenden closes the page. Both apply at once, without restarting Claude Desktop.

6. Try it. Ask "Which Lexware Office account are you connected to?" The answer names the company the key belongs to.

Worth knowing:

• Failed until step 5. Nothing is enabled after installing, so Claude Desktop shows the server as failed, offering no tools, until the setup page has saved some.
• The install dialog asks for nothing. It warns that an extension can reach everything on your computer, which is true of every local MCP server, this one included. The server's dependencies are installed on its first start, the versions in this project's lockfile.
• The setup page ends itself after 30 minutes without use.
• Every release attaches its own bundle too, the version in the file name, for installing a particular one.
• One or the other. The extension and an entry for the same server in claude_desktop_config.json would offer every tool twice. Remove the entry when you switch to the extension.
• The configuration is shared. The extension reads the same per-user .env and tools.json as an installation with uvx, so uvx benethos-lexware-office-mcp setup changes them too.
• Updating is installing the newer file over the old one. If Claude Desktop cannot replace it, end the setup page first with Beenden: while it runs, it holds the extension's files.
• A changed key applies once Claude Desktop is quit from the tray and started again. The first key does not need that, and until that restart neither does a change to it.
• Tried on Windows, with Claude Desktop from the Microsoft Store and nothing else installed. macOS is expected to work the same way and has not been tried.

With uvx, for any MCP client

The simplest way for any other client: no clone, no manual virtual environment, no git. uvx fetches the server and runs it on demand from PyPI (published as benethos-lexware-office-mcp).

1. Install uv, if you have not already — the uv installation page covers every platform. It brings uvx, and that is the only thing needed here.

2. Configure the server. Nothing has to be installed for this: uvx fetches the package and runs it.

uvx benethos-lexware-office-mcp setup

That opens the interface described under Configuring it in a browser: key, settings and one checkbox per tool. Everything it does can also be done by hand — start a settings file with uvx benethos-lexware-office-mcp --settings-sample > config/.env, put the key in it, and use --tools as described below.

Check that it works:

uvx benethos-lexware-office-mcp --help

3. Point Claude Desktop at it in claude_desktop_config.json:

{
  "mcpServers": {
    "benethos-lexware-office-mcp": {
      "command": "uvx",
      "args": ["benethos-lexware-office-mcp"]
    }
  }
}

No path from your machine appears in there, which is the point: uvx looks the package up by name. Two things worth knowing about that entry:

• Pin a version for stability: "args": ["benethos-lexware-office-mcp==0.6.2"]. Without a pin, uvx takes the newest release it can resolve, and a client restart is enough to change what it runs.
• uvx has to be on the PATH the client uses, which is not always the one your terminal has — some GUI clients pass a reduced environment. If the server does not start, put the absolute path to uvx in command, and restart the client fully rather than reloading it.

Would rather have a command of your own? uv tool install benethos-lexware-office-mcp gives you benethos-lexware-office-mcp without the uvx in front, which is worth it if you change permissions from the command line often. It buys nothing else: the same version can be pinned either way, and a warm start differs by tens of milliseconds. One thing to know — uv installs it into its own tool directory, which is not on the PATH of a fresh install. It says so when it finishes. Run uv tool update-shell and open a new terminal.

From the sources instead, to develop or to run something unreleased:

git clone https://github.com/benethos-hub/lexware-office-mcp
cd lexware-office-mcp
uv sync
uv run benethos-lexware-office-mcp setup

A client then needs the interpreter of that checkout's virtual environment, command pointing at .venv/Scripts/python.exe on Windows or .venv/bin/python elsewhere, with args of ["-m", "benethos_lexware_office_mcp"].

No key in there, on purpose. The server finds it in the .env. A client's configuration file is the wrong place for a credential: it is not yours — another program owns it, decides where it lives and when it rewrites it. It is the file people screenshot when they ask for help with an MCP setup, it is readable in the client's own settings view, and it travels to the next machine with the rest of that client's configuration. The .env is at least a file this project documents, that nothing syncs on your behalf, and that the configuration interface writes without ever showing the key back to you.

That .env is already the part worth being careful with. It holds a credential for a live accounting system, so keep it out of version control, out of shared folders and out of backups other people can read. When you stop using the server, delete it and revoke the key under Extensions, Public API — revoking is the only step that actually ends access.

4. Restart Claude Desktop fully — quit it from the tray rather than closing the window. That is for the configuration file you just edited, which a client reads once at startup, and it is what a changed setting in the .env needs too — the server reads those at startup as well. It is not needed for permissions: change those later and the running client is told, see Switching individual tools off. Nor for the first API key: a server started without one uses a key saved later from its next call on, and reads it again on every call until it is restarted, so a change to that key applies at once too. Changing a key the server was started with does need the restart.

Configuring it in a browser

uvx benethos-lexware-office-mcp setup

Or from your client: over stdio the server offers a prompt called Set up Lexware Office, and picking it opens the same pages. In Claude Desktop it is under the plus in the message box, in Connectors under the server's name. There the model cannot start it, only you can, and it does nothing but open the pages. That guard is the client's, not the server's: a client that hands its prompts to the model, as some agent frameworks and editors do, lets the model open the pages too. With such a client set LXO_MCP_SETUP_PROMPT=0, and the prompt is not offered.

Four pages on http://127.0.0.1:8771/, closed with Beenden in the sidebar or Ctrl+C. The port is one above the HTTP transport's 8770, so both can run at once, and --port picks another. They write the same files the command line does, so you can use either or both. The screens are in German, because Lexware Office is sold for German companies only, and each is named below by what it does with its label in brackets.

Overview (Übersicht) — where the installation stands, in three rows: the key stored or missing, how many tools are on and what they cost, and what the last connection test found. The first row in red is the next step, and the button at the top right goes there. Below it the "args" entry that makes a client use the same files, and which files those are and whether each exists yet.

Credentials (Zugangsdaten) — the API key, checked against the API before it is saved unless you say otherwise, and beside it the connection test: one call on the button, never on page load, and the account it found. The key is never shown back to you, never logged and never exported. If an environment variable is setting it, the page says so, because that would override whatever you save. A server that started without a key uses the one saved here from its next call, and reads whatever is saved here again on every call until it is restarted. A key that replaces one the server was started with applies once the client starts it again. The token of the HTTP transport is folded underneath, open when the server is set to that transport.

Permissions (Rechte) — one checkbox per tool, grouped, with the presets as buttons and the save button at the top right beside the count. On a fresh installation with no policy file yet, the reading tools come pre-ticked as a starting point — a proposal in a form, not a permission: there is still no file and therefore still no tool until you press save, and the page says so. Each row carries what that tool costs the assistant in context, and the total follows your ticks: every enabled tool is sent to the model on every request, so switching one on is a budget decision as well as a permission one. Writing tools are marked, and the ones whose result the API cannot take back are marked separately: nur App for a contact, which Lexware Office deletes without ceremony, and nur App · Buchhaltung for a record that enters the books. Neither means it is stuck — nothing is festgeschrieben when it is created, and a legend on the page names the four things that do bind a record later.

Profiles live here too. Save the current selection under a name, load it later. Loading only fills the boxes: nothing reaches tools.json until you press save. A name that is already taken is refused rather than quietly replacing what is there — case and spacing do not make a second profile — and replacing one is its own button beside the list. They are stored in tool_profiles.json beside the policy file.

The policy file itself can be downloaded and read back in from the same page — the file as it is, so it works on another installation with or without this interface, and a tools.json written by --tools reads here. Reading one only ticks the boxes, and saving is still a separate press. A tool the file does not mention stays off and the page says how many those are, which is what --tools sync does on the command line.

Settings (Einstellungen) — the thirteen settings that are not secret, in four cards: the connection, the output, the files, and whether the client is offered the prompt that opens these pages. An empty field means the built-in default, which the placeholder shows. A setting a real environment variable holds is shown rather than offered, since saving over it would change nothing.

Three things worth knowing. Every start makes a start code, and the address it prints carries it: http://127.0.0.1:8771/?code=…. Without a valid code every page shows one field, Code eingeben, so another program or another user on the same machine cannot open the pages through the loopback port. The code lives as long as the process, and after five wrong ones each further try waits. The browser setup opens signs in with a second code that works once, since a browser's address can stay readable in its command line for other users of the machine. It binds 127.0.0.1, because the code travels in the clear and keeps nobody out who can read the traffic. --host exists for a container, where the host-side publish keeps the port local, see In a container. Anywhere else a bind beyond loopback leaves the pages open to whoever reaches the port and reads the code, and the start says so. And it is a separate command: the MCP server never serves HTTP, and a client such as Claude Desktop starts that one, not this.

--port N moves it, --no-browser only prints the address, --exit-when-idle N ends it after N minutes without a request, which the prompt sets to 30, and --env-file and --tools-file say which files it edits. Unlike everywhere else those files do not have to exist yet. --public-port N is for a container published under another port than the one it binds: the address it prints and opens names that one.

If your client starts the server with --tools-file, give setup the same argument — otherwise it edits a different file and reports success. Both processes fix their files when they start and never change them afterwards, and neither can see how the other was started. The overview prints the "args" line that makes your client match the files the interface is holding, which is the easier direction.

Switching individual tools off

One JSON file decides what this server offers, and nothing else does. Either tick the boxes under setup above, or start the file with

uvx benethos-lexware-office-mcp --tools read-only

which writes every tool into tools.json, reading ones on and the rest off, and prints what it did. Three presets, each containing the last:

--tools show only reports. --tools-file PATH says where to write, and works with all of them — --tools write --tools-file ./tools.json creates the file there.

A preset overwrites the whole file, so hand edits are lost. Use one to start a file, not to update one. After an upgrade brings new tools, run --tools sync: it writes them in as off, leaves every flag you set alone, and never switches anything on. That last part is why it is the only one of these safe to run from a script.

The third step is its own because it is its own decision: what is deleted is gone, so it should be chosen by naming it rather than by picking the largest option. Exactly one tool carries such an effect, delete_article, and that is not a temporary state of affairs — an article is the only thing this API can delete. Nothing can be finalized or voided after the fact either, and the one thing that can be booked afterwards, an unchecked voucher, needs the assistant to pass finalize and confirm to update_voucher - which it may only do when you asked for it.

Without --tools-file, the file is searched exactly like the .env, lowest precedence first:

1. the per-user configuration directory
2. config/ of a checkout, when you are running from the sources
3. config/ and then the root of the working directory

The last one found wins, and a file nobody has created yet resolves to the first. After that, edit it:

{
 "create_contact": false,
 "search_contacts": true,
 "upload_file": false
}

A tool set to false is not listed and cannot be called. A tool the file does not mention is also off — silence is a refusal, so a tool that arrives with an upgrade waits for you rather than appearing on its own. No file at all means no tools at all, which is why --tools is part of setting the server up.

The file is read as the tool list is built and again on every call, so an edit takes effect at once in both directions — no restart. The server also tells the client when the set of enabled tools changes, so it fetches the list again by itself: Claude Desktop picks a change up while it is running. Nothing depends on it either way, since a tool that has been switched off cannot be called whatever list the client is still showing. If yours does not notice, restart it — Claude Desktop by quitting it from the tray.

Each tool also declares what it is — reading or writing, which group it belongs to, and whether what it writes can be removed again. That classification is what --tools read-only selects on and what the browser interface groups and marks by. It never decides a call: only the file does.

Configuration

Where a value comes from, and which one wins

One .env applies, never several. These are the places it is looked for, lowest first, and the highest one that exists is the file — the others are not read:

1. .env in the per-user configuration directory
2. config/.env of the checkout the server runs from, if it runs from one
3. config/.env and then .env in the working directory

--env-file names it instead, and then no search happens at all. That is the same rule --tools-file follows for the policy file, so both flags mean the same thing: this file, and nothing else.

Two things sit outside that file, one below and one above:

• the built-in default, for a setting no file mentions
• a real environment variable, which beats whatever the file says, unless it is empty: an empty one counts as not set

The last one is the one that surprises people. A setting exported in your shell, put in a client's env block, or pinned in a Compose file cannot be changed by editing a .env — not by hand, and not through setup. The value is written, the file is correct, and nothing happens.

The configuration interface says so rather than letting you find out: each setting carries a badge naming its source, and one that an environment variable is holding is marked as such. When something you saved seems to be ignored, that badge is the answer.

In a container this is not an edge case. The Compose files pin the transport, the bind address, the port and the allowed hosts as real environment variables, because those belong to the container rather than to the installation inside it. Everything else — the API key, the HTTP token, the limits — is left to the config volume, which is what makes the configuration interface able to change it.

The same order applies to the policy file, and LXO_MCP_TOOL_POLICY and --tools-file name one directly. The interface pins whichever file it found when it started, so the page cannot swap its own subject out from under you.

Naming the files

--env-file PATH names a settings file instead of searching, and pairs with --tools-file so that one entry in a client's configuration carries its own account and its own permissions:

"args": ["--env-file", "/path/to/test.env",
         "--tools-file", "/path/to/test-tools.json"]

A path that does not exist is refused rather than quietly falling back to the search — except under setup, which exists partly to create one.

setup writes this file for you.

The settings

Every setting above is in use. LXO_MCP_PAGE_SIZE is capped at 250, which is the lowest page size any endpoint accepts, and a larger value is refused at startup rather than turning into an API error later. search_articles asks for at least 25 whatever it says, because that endpoint refuses less.

Transport

stdio is the default and what Claude Desktop and comparable local clients use: the client starts the server as its own child process, and nothing else can talk to it.

streamable-HTTP and SSE serve the same tools on a port, for a container or a machine of their own:

uvx benethos-lexware-office-mcp --transport streamable-http --port 8770

Two things stand in front of that port, and neither is optional. A bearer token every request must carry as Authorization: Bearer <token> — without LXO_MCP_BEARER_TOKEN the server refuses to start an HTTP transport at all, because anyone who can reach the port could otherwise spend your Lexware credentials. And the SDK's DNS-rebinding guard, which checks Host and Origin against an allowlist of the loopback names, extended by --allowed-hosts where a container or a proxy puts another name in front.

Neither makes the port safe to publish on a network. They make it survivable on a machine shared with other processes. --host binds somewhere other than loopback, which a container has to do — see In a container for why that is not the relaxation it looks like.

In a container

The image is published for linux/amd64 and linux/arm64, so nothing from this repository is needed to run one:

docker pull ghcr.io/benethos-hub/benethos-lexware-office-mcp:latest

Pin a version for anything you depend on - :0.6.2 for an exact release, :0.6 to follow its patch releases. :latest moves with every release, and :edge is built on demand from whatever main holds and is not a release at all.

The image carries the package's name, every release from 0.2.0 on. It was published as ghcr.io/benethos-hub/lexware-office-mcp until 0.4.2, and the earlier releases were copied over with the same digest, so a tag pulls the same bytes under either name. The old name got the 0.4 patch releases and none from 0.5.0 on. Pulling that name, change it to the one above: the volumes stay as they are.

With Compose

containers/production/ runs the published image, and that folder is all it needs. Into an empty folder:

mkdir lexware-office-mcp && cd lexware-office-mcp
for file in compose.yaml .env.example Caddyfile README.md; do
  curl -fsSL -o "$file" "https://raw.githubusercontent.com/benethos-hub/lexware-office-mcp/main/containers/production/$file"
done
cp .env.example .env                      # names the image's version
docker compose up -d                      # the server, on 127.0.0.1:8770
docker compose --profile setup up -d      # add the configuration interface
docker compose rm -f -s setup             # take the interface away again

Not docker compose --profile setup down. That is the whole project: it takes the server down with it. rm -f -s setup stops and removes the one service and leaves the server running. docker compose stop setup also works and keeps the stopped container around for next time.

To update, set LXO_VERSION in .env to the new version, then docker compose pull && docker compose up -d. The .env beside compose.yaml holds only that, the ports on the host and HTTPS. The server's own settings live in its config volume.

HTTPS for the local network is Caddy in front of the server, behind the profile https: COMPOSE_PROFILES=https and a name in LXO_DOMAIN, and clients on other machines reach https://<name>/mcp on port 443. The certificate comes from Caddy's own CA, whose root each client trusts once, and Caddy passes on the MCP path alone, never the configuration interface. The folder's README has the steps. A public address is not what it is for: one bearer token is all this server knows of who is asking.

The Compose file used to sit in the repository root and build from the checkout. containers/production/ keeps its project name, so its volumes carry over with the key, the token and the tools: docker compose up -d there replaces the container and keeps them. Building from a checkout is containers/development/, which runs beside an installation in operation under a project of its own, on ports 8780 and 8781, and never touches its volumes.

Docker keeps at most five log files of 10 MB for each service, the oldest dropped first. The server writes a line for every request it refuses, and at DEBUG for every one it receives, so without a cap a reachable port would grow the log for as long as the container exists.

As single containers

docker run -d --name lexware-office-mcp \
  --restart unless-stopped \
  --log-opt max-size=10m --log-opt max-file=5 \
  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  -p 127.0.0.1:8770:8770 \
  -v lxo-config:/config -v lxo-downloads:/downloads \
  ghcr.io/benethos-hub/benethos-lexware-office-mcp:latest

The token it generated for itself is in the config volume, which is where you read it from:

docker exec lexware-office-mcp grep LXO_MCP_BEARER_TOKEN /config/.env

That one line rather than the whole file: once a key has been entered, the API key sits in there too, and it has no business scrolling through a terminal you might screenshot.

The configuration interface is the same image with its other command, pointed at the same volume:

docker run --rm -d --name lexware-office-mcp-setup \
  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  -p 127.0.0.1:8771:8771 \
  -v lxo-config:/config -v lxo-downloads:/downloads \
  ghcr.io/benethos-hub/benethos-lexware-office-mcp:latest \
  setup --no-browser --host 0.0.0.0 --port 8771 \
        --env-file /config/.env --tools-file /config/tools.json

Published under another port, -p 127.0.0.1:9000:8771, add --public-port 9000, so the address in its log names the port to open.

Its log has the address with the start code, which is the line to open:

docker logs lexware-office-mcp-setup 2>&1 | grep "interface at"

It was started with --rm, so stopping it is also the end of it:

docker stop lexware-office-mcp-setup

--restart unless-stopped is not decoration here. The container ends its process when the settings file changes, which is what carries a saved setting into a running server. With no restart policy it ends and stays ended.

The rest of the second line is hardening, and the Compose files do the same. The server writes nothing but its two volumes and /tmp, so the image itself can stay read-only, and a process of an ordinary user on a port above 1024 needs no Linux capability at all.

Turn the interface off when you are done

Open the address from its log, docker compose logs setup with Compose, enter the key, tick the tools — and then stop it, with Beenden in the sidebar or one of the commands below. The address names the port it is published on, which both Compose files pass in from LXO_SETUP_PORT as --public-port. Nothing stops it for you. It accepts an API key behind a code that travels in the clear, and it will happily keep serving that page for as long as the machine is up. Beenden ends the process and leaves a stopped container behind, which docker compose rm -f -s setup removes, and a docker run --rm one removes itself.

docker compose rm -f -s setup             # Compose
docker stop lexware-office-mcp-setup      # a single container
docker ps --filter name=setup             # nothing listed means it is off

The server is meant to run. The interface is meant to run for the minutes you are configuring in it, which is why a plain docker compose up leaves it out and why it has no restart policy: once stopped, it stays stopped until you ask for it again.

Nothing has to be prepared first. On its first start the server makes a bearer token, writes it into the config volume and says so — the interface shows it, and that is the value a client needs. It is not baked into the image, where every copy would share it.

The container binds 0.0.0.0, and that is not a relaxation. A process on the container's own loopback cannot be reached through a published port at all. The isolation is the network namespace, and who may reach the port is decided by the publish, which maps 127.0.0.1 only.

A setting saved in the browser reaches the running server. Settings are read once at startup, so the container is told to end when its settings file changes and Compose starts it again a second later. A client's open stream holds that end back for five seconds at most, then the connection is closed and the client reconnects to the new process. What Compose pins as real environment variables — the transport, the bind address, the port, the allowed hosts — belongs to the container and cannot be changed from the volume, see Configuration.

Logs

Everything goes to stderr. At INFO that is one line per tool call: what it read or wrote, named by its Lexware id, its number of rows or its size, how many API calls it made and how long it took. A refused or failed call is a WARNING naming the error's class, and for a refusal by the API its status and error codes. DEBUG adds a line per API attempt and one per HTTP request. LXO_MCP_LOG_LEVEL sets the level.

2026-09-30T13:58:50.597+02:00 INFO     tools: search_contacts read 12 rows in 1 API call, 230 ms

The time is local, to the millisecond, with its offset. At a terminal the level and the source are coloured, unless NO_COLOR is set.

A line never carries what the assistant sent or what the API answered: no search term, name, amount or file name, and no query string. The libraries underneath stay at WARNING for the same reason, since their INFO lines carry request URLs and error text. The configuration interface writes a line for everything it saves, and never the key, the token or a setting's value.

Example prompts

Once the server is connected, prompts like these are the intended use:

• "Which invoices are still open, and which of them are overdue?"
• "Show me everything we billed customer Muster GmbH this quarter."
• "What does invoice RE-2024-0142 contain, and has it been paid?"
• "Find the article with number A-1007 and tell me its current price."
• "Download the PDF of the last credit note we issued."
• "Give me a link to open voucher X in Lexware Office."

Rate limits

The Lexware API allows two requests per second, enforced with a token bucket. That budget is global — it covers all endpoints of the API at the same time, so reading a contact and reading an invoice draw from the same allowance.

The server mirrors this with a single token bucket shared by every request in the process, refilling slightly below the documented rate by default. Lexware notes that enforcing the limit exactly, without a buffer, tends to produce 429s anyway once network jitter shifts the arrival times, so the default leaves headroom. Requests are serialized through that bucket rather than fired in parallel, which means a broad question touching many documents gets slower instead of blocked.

Two things worth knowing:

• The budget belongs to your account, not to this process. A second instance of the server, another integration, or a script you run yourself all spend from the same two per second.
• Lexware warns that a client which keeps hammering after a 429 can stay blocked permanently. The server therefore backs off exponentially and gives up after a few attempts rather than retrying harder.

The account's bucket was measured on 2026-08-21 and holds four: five requests fired at once got four through and one refused. The default of 2 leaves half of that for everything else drawing on the same account — the web app, another integration, a second instance of this server. Raise it to 4 only if you know this server is the only consumer.

Both limiter values are configurable via LXO_MCP_RATE and LXO_MCP_BURST if your account behaves differently.

Development

uv sync --extra dev
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy

The test suite is fully offline. It mocks the HTTP layer and needs no API key, so it runs anywhere. Two kinds of test leave the process without leaving the machine: three start the server as a real subprocess and speak MCP to it over stdio, which is also what proves that nothing writes to stdout on the startup path, and the configuration interface is driven through a real loopback HTTP server with a real cookie jar, because its CSRF guards are only worth testing the way a browser meets them.

No API key ships with this repository and none belongs in CI, so a checkout can never talk to Lexware on its own. Checking the server against the real API is therefore always a deliberate local run with a key you supply, separate from the suite above and never part of it:

uv run python live/smoke.py
uv run python live/smoke.py --env-file path/to/.env

It reads your account and writes nothing to it. The server it builds gets the read-only preset, so the writing tools are not there to be called at all. It prints what it checked, what the account had nothing for, and what failed, and it masks record ids so the report can be pasted somewhere. pytest never runs it. See SPECS.md section 14.1 for why a live check is not a gate.

Contributions and issues are welcome. SPECS.md is where design decisions are recorded, with the reasoning and the measurements behind them.

License

MIT. See LICENSE.

Trademarks and affiliation

This project is not affiliated with, endorsed by, or sponsored by Lexware, Haufe-Lexware GmbH & Co. KG, or any of their subsidiaries. "Lexware" and "Lexware Office" are trademarks of their respective owners and are used here only to name the API this software integrates with, in a descriptive sense.

The software talks exclusively to the documented public API using credentials that the account owner supplies and can revoke. Use of that API is governed by Lexware's own terms, which you accept independently of this project.