Lexware Office MCP Server
An MCP server for Lexware Office (formerly Lexoffice). It lets MCP-capable assistants query and manage contacts, sales documents, vouchers, files, payments, webhooks, and reference data through the Lexware Office public API.
The server uses Code Mode: instead of one MCP tool per API endpoint, it exposes two tools — search to explore a curated Lexware API catalog and execute to run constrained, sandboxed API workflows. This keeps the tool surface small while covering the whole API, including pagination, aggregation, and multi-step reporting in a single call.
Upgrading from 1.x? The legacy tool-per-endpoint server was removed in 2.0.0. See docs/guide.md#migrating-from-1x.
Features
- Broad Lexware Office API coverage for read and write workflows
- Sales documents: invoices, quotations, order confirmations, credit notes, delivery notes, dunning notices, and down-payment invoices
- Contact management: create, read, and update customers and vendors
- Bookkeeping: vouchers, posting categories, payments, and file uploads
- Reference data: profile, countries, print layouts, payment conditions, recurring templates
- Webhooks: create, list, inspect, and delete event subscriptions
- Read-only by default: writes require explicit opt-in via environment variable
How it works
The server exposes two MCP tools:
search — runs a sandboxed JavaScript async arrow function against a curated OpenAPI-lite Lexware catalog.execute — runs a sandboxed JavaScript async arrow function with one host capability, lexware.request, for relative /v1/... Lexware API calls.
Example execute call:
async () => {
const response = await lexware.request({
method: 'GET',
path: '/v1/contacts',
query: { name: 'Muster', page: 0, size: 10 }
});
return response.data;
}
The sandbox does not receive the Lexware API key, Node globals, filesystem access, imports, fetch, or arbitrary network access. lexware.request only accepts relative /v1/... paths and sends the API key from the host process.
Binary-safe file uploads
Uploads are binary-safe via multipart parts with contentPath (host reads a local file from disk), contentBase64 (binary FormData parts), or bodyBase64 (raw binary body). The host reads/decodes and builds Buffer / Blob bodies outside the QuickJS sandbox.
Preferred: contentPath — pass the file's absolute path instead of inlining bytes. Requires LEXWARE_OFFICE_ALLOW_WRITES=true (uploads are writes) and works only when the MCP server runs on the machine that has the file:
async () => {
const response = await lexware.request({
method: 'POST',
path: '/v1/files',
multipart: [
{ name: 'file', contentType: 'application/pdf', contentPath: '/absolute/path/to/receipt.pdf' },
{ name: 'type', value: 'voucher' },
],
});
// response.sent echoes { bytes, parts: [{ name, filename, bytes, sha256 }] } for integrity checks
return { id: response.data?.id, sent: response.sent };
}
See docs/guide.md for details and all supported modes.
Configuration
Get a Lexware Office API key
Create an API key at https://app.lexoffice.de/addons/public-api.
Prerequisites
- Node.js 22 or higher
LEXWARE_OFFICE_API_KEY environment variable
Claude Desktop / MCP config with NPX
Recommended: consume the packaged server
Run the packaged binary from the latest GitHub release (#semver:^2 resolves to the newest v2.x tag and picks up future releases automatically). The package builds itself during GitHub installs via prepare, so users do not need to clone the repository or commit build/ artifacts.
{
"mcpServers": {
"lexware-office": {
"command": "npx",
"args": ["-y", "--package=github:JannikWempe/mcp-lexware-office#semver:^2", "lexware-office"],
"env": {
"LEXWARE_OFFICE_API_KEY": "YOUR_API_KEY_HERE",
"LEXWARE_OFFICE_READ_ONLY": "true"
}
}
}
}
Troubleshooting: If the npx command above fails during git-dependency preparation with an error mentioning --before, your npm user config may contain minimum-release-age, which conflicts with npm's internal --before flag. Two fixes:
# Option 1: bypass your user config for this invocation
NPM_CONFIG_USERCONFIG=/dev/null \
npx -y --package=github:JannikWempe/mcp-lexware-office#semver:^2 lexware-office
# Option 2: remove the conflicting setting permanently
npm config delete minimum-release-age --location=user
When this package is published to npm, replace the GitHub package spec with the npm package name:
"args": ["-y", "--package=mcp-lexware-office", "lexware-office"]
Local development from TypeScript source
For local development, you can run the TypeScript source directly with tsx after cloning the repo and installing dependencies:
{
"mcpServers": {
"lexware-office-local": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/mcp-lexware-office/src/index.ts"],
"env": {
"LEXWARE_OFFICE_API_KEY": "YOUR_API_KEY_HERE",
"LEXWARE_OFFICE_READ_ONLY": "true"
}
}
}
}
Use this source-based setup only for development. End users should prefer the packaged binary above.
Write safety
The server is read-only by default. POST, PUT, PATCH, and DELETE requests are blocked unless you explicitly opt in:
{
"LEXWARE_OFFICE_ALLOW_WRITES": "true"
}
LEXWARE_OFFICE_READ_ONLY=true is a hard block that wins over ALLOW_WRITES=true:
{
"LEXWARE_OFFICE_READ_ONLY": "true"
}
See docs/guide.md#permissions for the detailed permission model.
Docker
Build the image:
docker build -t mcp-lexware-office:latest -f src/Dockerfile .
Run it:
docker run -i --rm \
-e LEXWARE_OFFICE_API_KEY \
-e LEXWARE_OFFICE_READ_ONLY=true \
mcp-lexware-office:latest
Build and test
npm run build
npm test
Documentation
License
MIT. See LICENSE.
