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.

This is a customized fork of JannikWempe/mcp-lexware-office (MIT-licensed), with two added tools — match_bank_csv_to_vouchers and match_receipts_to_bank_csv — for reconciling a bank statement CSV against Lexware vouchers or scanned receipt PDFs. See Bank reconciliation tools below. All search/execute Code Mode functionality is unchanged from upstream.

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.

Bank reconciliation tools

Two additional MCP tools (outside Code Mode, no sandbox involved) for matching a bank statement CSV against Lexware data:

Tool	Description
match_bank_csv_to_vouchers	Parses a bank CSV and matches transactions against Lexware vouchers (invoices, receipts, credit notes, ...) fetched live from /v1/voucherlist.
match_receipts_to_bank_csv	Extracts amount/date from receipt PDFs (passed as base64) and matches them against a bank CSV the same way — for reconciling scanned receipts that aren't in Lexware yet.

Matching logic: amount-first — a transaction only matches a candidate (voucher or receipt) with the exact same EUR amount (sign-insensitive: bank exports show debits as negative, voucher/receipt totals as positive). Among amount matches, only one falling inside dateToleranceDays (default 3) counts as a match; zero or more than one date-window match is reported as unmatched with the amount-only candidates listed for manual review. Ambiguous data is never silently guessed — a wrong match in bookkeeping reconciliation is worse than an unmatched transaction.

Bank CSV format: auto-detects the delimiter from the header line (; for German exports, , otherwise — needed because German amounts use , as the decimal separator) and common column names: Datum/Date/Buchungstag for the date, Betrag/Amount/Umsatz for the EUR amount.

Receipt PDF extraction is a best-effort regex over the PDF's text layer (looks for "Gesamtbetrag/Gesamt/Total/Brutto: X,XX €" and dd.mm.yyyy/yyyy-mm-dd dates). It does not OCR scanned images without a text layer — check extractionIssues in the result and review those manually.

Voucher search: voucherType/voucherStatus default to Lexware's any wildcard and accept comma-separated values (e.g. purchaseinvoice + open,paid) to narrow the search. The date range sent to /v1/voucherlist is padded by dateToleranceDays (+1 day) so vouchers just outside the transactions' own date span aren't missed. The endpoint caps out at 10,000 matching entries — narrow the filters or split the CSV by date range if you hit that.

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 straight from this fork's main branch. 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:bdiaby1/claude_lexware_mcp_2#main", "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:bdiaby1/claude_lexware_mcp_2#main lexware-office

# Option 2: remove the conflicting setting permanently
npm config delete minimum-release-age --location=user

If you tag releases later, #semver:^2 (instead of #main) will pick the newest matching tag automatically. 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

• Guide and migration notes
• Lexware Office API key setup

License

MIT. See LICENSE.