Lexware Office MCP Server

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
  • As an extension that updates itself
  • 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.9.0. 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 tool but server_status, which says what is running and reads nothing in the account. 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, server_status aside, which only says what is running, 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, except one, which is there whatever the file says. It reads no record and writes nothing:

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 network path such as \\server\share\receipt.pdf is read only when the directory is on that same share.

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, pinned to its release or updating itself. 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:

• Only server_status until step 5. Nothing else is enabled after installing, so that is the one tool Claude Desktop lists 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.
• Your own files, if you have them. The extension's page under Settings → Extensions has two fields, Settings file (.env) and Tool policy file (tools.json). Left empty, 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. Pick a file there and Save, and the server restarts on it at once, while Claude Desktop keeps the tools it had until it is quit from the tray and started again. The second field can stay empty when the .env names the policy file with LXO_MCP_TOOL_POLICY.
• 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, or any other setting in the .env, 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. Ticking tools does not need it either.
• 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.

Windows with Smart App Control on. The extension may not start there, and its tools never appear. Claude Desktop runs it through uv, and on a machine without uv it downloads a copy of its own. Smart App Control judges a program by its signature and reputation, and it can block that copy, which Windows records as a Code Integrity block of uv.exe. The same goes for the .exe launchers uvx writes. The way around is a virtual environment made from the python.org installer, py -m venv and pip install benethos-lexware-office-mcp into it, and a client entry that starts its python.exe with -m benethos_lexware_office_mcp, with no generated program in between. Whether to keep Smart App Control on is a decision about the whole machine, not about this server.

As an extension that updates itself

The extension above runs the release it was downloaded with, and a new release means a new download. A second extension runs the newest release on PyPI instead, so a new release arrives with a restart of Claude Desktop. It holds the same key to the same books, so read the list below first. The pinned extension is the choice for anyone who wants to look at a release before it runs.

1. Download benethos-lexware-office-mcp-auto-update.mcpb. Every release carries it, the copy with a version in its name as well. Any of them runs the newest release, the version only says which release built it.
2. Install and set it up as under As a Claude Desktop extension, from step 3. Install this one or the pinned one, not both, or every tool shows up twice. Installing one does not remove the other, so when you switch, remove the old one under Settings → Extensions. The per-user files stay, and a file picked on the old one's page has to be picked again.

How and when it updates:

• At the start of the server, not during a chat. Claude Desktop starts it with uv tool run benethos-lexware-office-mcp. uv looks for a newer release only then, when Claude Desktop starts or reconnects the extension. To pick up a release, quit Claude Desktop from the tray and start it again.
• Up to 10 minutes late. uv keeps PyPI's list of releases for 10 minutes, as PyPI tells it to, so a release published in between arrives with the first restart after those 10 minutes.
• It needs to reach PyPI. Once the 10 minutes are over, uv asks PyPI before it starts the server, and without an answer it stops with Failed to fetch instead of falling back to the release it has. A network that blocks PyPI keeps this extension from starting. The pinned one is the choice there.
• The first start after a release takes longer. uv downloads and installs the new release and its dependencies once, a few seconds, and later starts reuse them.
• The running version is the one server_status names. Claude Desktop's extension list shows the version of the file it was installed from, and that stays as it was.
• A copy from uv tool install wins. uv then runs that one, whatever PyPI has, and nothing updates. uv tool uninstall benethos-lexware-office-mcp removes it.
• uv's own configuration counts too. An exclude-newer in a uv.toml of yours holds this extension on an older release, and nothing says so but the version server_status names.
• A new tool stays off, an enabled one can grow. A tool the policy file does not name is not offered, whichever release brought it. A tool you enabled keeps its name and can gain abilities under it: update_voucher learned to book a voucher in 0.3.0, and the upload tools to fetch from the addresses LXO_MCP_UPLOAD_URLS allows in 0.6.0. Such a change arrives with a restart, without asking, and the changelog says what it was.
• Dependencies move within patch windows. uv takes the newest versions each release allows, as uvx does, not the tested set in uv.lock that the pinned extension and the container image run. The packages this server names itself, such as mcp and httpx, may move by a patch, and a new minor of one of them arrives with a release here. The packages beneath them are not held back, so one of those can still change without a release. A check in this repository runs the newest versions allowed every day and after each release, installs the published package from PyPI as this extension does, and opens an issue when the server stops answering a client correctly. It holds no key and reaches no account, so a change in what a call sends to Lexware passes it.
• Smart App Control blocks it as it blocks the pinned extension, see the note above.
• Tried in Claude Desktop on Windows, from the Microsoft Store: the first start, the setup page, both file fields and a change of version at a restart, brought about by hand. A real release arriving through PyPI has not been tried with this extension, and neither has macOS.

If it fails:

• It can come without a release of this project. A dependency moves while this server's version stays the same, so server_status naming the version that worked yesterday proves nothing, and two machines on one version can run different dependencies. server_status names the mcp in use, the one of the six most likely to matter.
• A crash shows. The extension does not start and its tools are missing from the chat, or a tool answers with an error. The reason is in Claude Desktop's log folder, in mcp-server-<extension name>.log, uv's own messages included.
• A wrong result does not have to. A dependency that changes a request or a field can leave the server running with no error anywhere. If an answer looks off, compare it with Lexware Office itself before relying on it.
• Nothing rolls back on its own. uv runs the newest versions at every start. Once something broke, every restart runs it again, until a release fixes it, and the auto-update file of an older release runs the newest release as well.
• The way out is the pinned extension. Remove this one and install benethos-lexware-office-mcp-X.Y.Z.mcpb of a release that worked, from the releases page. It runs that release with the versions tested for it, and stays there until you install another. Please open an issue with the log, so the fix comes sooner.

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. Add it to your client. No path from your machine appears in either entry below, which is the point: uvx looks the package up by name.

Claude Desktop, in claude_desktop_config.json:

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

Claude Code, with one command in a terminal:

claude mcp add benethos-lexware-office-mcp --scope user -- uvx benethos-lexware-office-mcp

• --scope user makes it available in every project. Left out, it is local, for the current directory alone. project writes it into a .mcp.json meant to be committed, which shares the entry with everyone who clones that repository.
• The prompt Set up Lexware Office is among the slash commands: type / and part of its name, and it opens the configuration interface in the browser.

Two things worth knowing about either entry:

• Pin a version for stability: "args": ["benethos-lexware-office-mcp==0.9.0"], or uvx benethos-lexware-office-mcp==0.9.0 at the end of the command. 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 the client. Claude Desktop fully — quit it from the tray rather than closing the window — and in Claude Code start a new session. That is for the entry you just made, 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.

Documentation truncated — see the full README on GitHub.