Benethos Lexware Office MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Benethos Lexware Office MCP listing page.
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
- Configuring it in a browser
- Switching individual tools off
- Configuration
- Transport
- In a container
- 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.5.3. 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_profileanswers 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 throughsetup, or edit by hand. Not a level, not a group:create_contacton andupload_fileoff 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
.envand 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:
| Tool | What it does |
|---|---|
get_profile | Company profile and connection check |
search_contacts | Find customers and vendors by name, email, number or role |
get_contact | One contact with addresses, roles and version |
search_articles | List articles, filtered by number, barcode or kind. The API offers no search by title |
get_article | One article with its price block and version |
search_vouchers | The central query — filter the voucher list by type, status, contact, document number, date range and what is still open |
get_sales_document | Read an invoice, quotation, credit note, order confirmation, delivery note, dunning or down payment invoice in full |
get_voucher | Read a bookkeeping voucher, by id or by its document number |
get_payments | Payment status and open amount of a voucher |
get_recurring_templates | Templates that issue invoices on a schedule, one or a page of them |
get_master_data | Countries, payment conditions, posting categories and print layouts, with a search to narrow them |
download_document | Save the rendered PDF or XML of a sales document |
download_file | Save a stored file, such as an uploaded receipt |
read_download | Put a downloaded file into the answer, for clients that cannot follow a resource link |
get_deeplink | Build a permalink to a sales document, contact or voucher in the web app, without an API call |
Write tools. These change real accounting records, so enable them one at a time and against an account you are willing to have changed:
| Tool | What it does |
|---|---|
create_contact | Create a customer or vendor |
update_contact | Change one, without touching what you did not name |
create_article | Add an article to the catalogue |
update_article | Change one, without touching what you did not name |
create_voucher | Record a bookkeeping voucher |
update_voucher | Change one that is already recorded, or book a receipt that upload_file left unchecked |
create_sales_document | Create an invoice, quotation, credit note, order confirmation, delivery note or dunning — a draft unless you ask for it to be issued, which the assistant may only do on your explicit instruction |
upload_file | Upload a receipt, which also creates its voucher |
attach_file_to_voucher | Hang a file on a voucher that already exists |
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:
| Tool | What it does |
|---|---|
delete_article | Remove an article. The API cannot bring it back. Takes confirm: true, and sends nothing without it |
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. What the server does not do
is announce a new download. It tells a client when the tool list changes,
but sends no list-changed notification for resources, so a client that lists
once at startup will not see anything fetched later in the session.
Between that and Claude Desktop not following resource links at all,
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:
| File | Arrives as |
|---|---|
| XML | text, so an XRechnung can actually be read |
| pictures of its pages, the first 10 by default | |
| Image | the image |
| Anything else | an embedded binary for the client to handle |
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 accepts 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.
Requirements
- uv, which brings
its own Python and the
uvxcommand 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
- Sign in to Lexware Office as the account owner.
- Open the public API add-on at https://app.lexware.de/addons/public-api.
- Create a key and copy it once — it is shown a single time.
- Keep it out of any file that goes into version control.
setupwrites it into the.envthe server reads, in the per-user configuration directory or, in a checkout, inconfig/.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.jsonwould offer every tool twice. Remove the entry when you switch to the extension. - The configuration is shared. The extension reads the same per-user
.envandtools.jsonas an installation with uvx, souvx benethos-lexware-office-mcp setupchanges 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.
- 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.
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:
3. Point Claude Desktop at it in claude_desktop_config.json:
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.5.3"]. Without a pin,uvxtakes the newest release it can resolve, and a client restart is enough to change what it runs. uvxhas to be on thePATHthe 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 touvxincommand, 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:
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. Changing a key it already has does need the restart.
Configuring it in a browser
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. The model cannot start it, only you can, and it does nothing but open the pages.
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. A key that replaces another applies once the client
starts the server 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 eleven settings that are not secret, in
three cards: the connection, the output, the files. 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 and opens carries it: http://127.0.0.1:8771/?code=….
Without it 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. 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
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:
| enables | |
|---|---|
--tools read-only | queries only |
--tools write | and creating and updating |
--tools irreversible | and deleting an article |
--tools sync | changes no flag, only adds the tools the file has not heard of |
--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:
- the per-user configuration directory
config/of a checkout, when you are running from the sourcesconfig/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:
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:
.envin the per-user configuration directoryconfig/.envof the checkout the server runs from, if it runs from oneconfig/.envand then.envin 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:
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
| Variable | Meaning | Default |
|---|---|---|
LXO_MCP_API_KEY | Your Lexware Office API key. Required. Visible ASCII only, so a space or an invisible character copied along with it is refused | — |
LXO_MCP_TOOL_POLICY | Per-tool on/off file, see below | tools.json, searched for the way the .env is |
LXO_MCP_BASE_URL | API base URL, https:// only, since the key travels there | https://api.lexware.io |
LXO_MCP_APP_BASE_URL | Web app base for deeplinks, https:// only | https://app.lexware.de |
LXO_MCP_DOWNLOAD_DIR | Where downloaded documents land | user cache directory |
LXO_MCP_KEPT_DOWNLOADS | How many downloads the directory keeps, newest first. Older ones are deleted, and fetched again when needed. Only in the default directory unless set, 0 keeps all, while the resource list still names the newest 100 | unset: 100 in the default directory, all in one you name |
LXO_MCP_UPLOAD_DIR | The only directory the upload tools may read from | anywhere |
LXO_MCP_TIMEOUT | HTTP timeout in seconds | 30 |
LXO_MCP_RATE | Requests per second, global across all endpoints | 1.5 |
LXO_MCP_BURST | Token bucket capacity. The account's own bucket holds 4 | 2 |
LXO_MCP_PAGE_SIZE | Rows per page a search requests and returns | 25 |
LXO_MCP_PDF_PAGES | Pages of a PDF read_download renders by default, at most 100 | 10 |
LXO_MCP_LOG_LEVEL | Level of this server's own lines on stderr. The libraries underneath stay at WARNING | INFO |
LXO_MCP_TRANSPORT | stdio, streamable-http or sse | stdio |
LXO_MCP_BEARER_TOKEN | Shared secret every HTTP request must carry. Required for an HTTP transport. Visible ASCII only | — |
LXO_MCP_HTTP_HOST | Address to bind for an HTTP transport | 127.0.0.1 |
LXO_MCP_HTTP_PORT | Port to bind | 8770 |
LXO_MCP_HTTP_PATH | URL path the transport serves on | /mcp |
LXO_MCP_ALLOWED_HOSTS | Host values to accept besides loopback, comma separated | — |
LXO_MCP_GENERATE_BEARER_TOKEN | Make a token at startup if none is set and write it to the settings file | off |
LXO_MCP_EXIT_ON_CONFIG_CHANGE | End the process when the settings file changes, for something that restarts it | off |
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:
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:
Pin a version for anything you depend on - :0.5.3 for an exact release,
:0.5 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:
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
The token it generated for itself is in the config volume, which is where you read it from:
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:
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:
It was started with --rm, so stopping it is also the end of it:
--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.
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.
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
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:
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.