Skip to main content
Glama
bdiaby1

Lexware Office MCP Server

by bdiaby1
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

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

Related MCP server: lexware-mcp-server

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

License

MIT. See LICENSE.

Available Tools

4 tools
executeA

Execute a constrained Lexware Office API workflow by running a JavaScript async arrow function.

Use search first when you need endpoint/domain guidance; do not guess Lexware paths from memory. The sandbox exposes no API key, filesystem, process, imports, fetch, or arbitrary network access.

Available globals:

declare const spec: LexwareApiCatalog; declare const lexware: { request<T = unknown>(input: LexwareRequest): Promise<LexwareResponse>; json(input: LexwareRequest): Promise; paginate<T = unknown>(input: LexwareRequest, options?: { maxPages?: number }): Promise<T[]>; requireNumber(row: unknown, fieldPath: string): number; requireMoney(row: unknown, fieldPath: string): number; sumMoney(rows: unknown[], fieldPath: string): number; formatMoney(cents: number, currency?: string): string; };

type LexwareRequest = { method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; path: string; // relative /v1/... only; no absolute URLs or // hosts query?: Record<string, string | number | boolean | Array<string | number | boolean> | null | undefined>; body?: unknown; // JSON by default; string when rawBody=true (UTF-8 encoded, NOT binary-safe) bodyBase64?: string; // raw binary body as base64; the host decodes it outside the sandbox multipart?: MultipartPart[]; // multipart/form-data uploads (e.g. POST /v1/files); host builds FormData contentType?: string; rawBody?: boolean; accept?: string; }; // At most one of body, bodyBase64, or multipart per request.

type MultipartPart = { name: string; value?: string; // plain text form field contentBase64?: string; // binary part content as base64; host decodes it contentPath?: string; // absolute file path on the MCP server machine; host reads the file directly — preferred for local files (no base64, no size blowup) filename?: string; // defaults to the contentPath basename contentType?: string; }; // Exactly one of value, contentBase64, or contentPath per part.

type LexwareResponse<T = unknown> = { ok: boolean; status: number; statusText: string; data?: T; text?: string; truncated?: boolean; contentType: string; headers: Record<string, string>; errorCategory?: string; retryAfterSeconds?: number; operation?: { operationId: string; method: string; pathTemplate: string; summary: string }; request: { method: string; path: string; query: Record<string, string[]> }; sent?: { bytes: number; sha256?: string; parts?: Array<{ name: string; filename?: string; bytes: number; sha256: string }> }; // echo of uploaded binary payloads for integrity checks };

lexware.request returns all HTTP responses, including non-OK, as LexwareResponse. Check response.ok/status for recovery logic, or use lexware.json(...) / lexware.paginate(...) when you want non-OK or non-JSON responses to throw.

This server is read-only by default. POST, PUT, PATCH, and DELETE are blocked unless the server is started with LEXWARE_OFFICE_ALLOW_WRITES=true. Setting LEXWARE_OFFICE_READ_ONLY=true is a hard block that overrides ALLOW_WRITES. Check spec.info.writesEnabled to branch before attempting a write.

Example:

async () => { const response = await lexware.request({ path: '/v1/contacts', query: { page: 0, size: 5 } }); return { status: response.status, request: response.request, data: response.data }; }

File upload example (bookkeeping Beleg). Never inline file bytes in code — pass the file's absolute path via contentPath and the host reads it from disk:

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' }, ], }); return { status: response.status, id: response.data?.id, sent: response.sent }; }

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesJavaScript async arrow function to execute a constrained Lexware API workflow
maxRequestsNoMaximum number of Lexware API requests this execution may perform.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility and delivers extensively. It discloses sandbox limitations (no API key, filesystem, process, imports, fetch, or arbitrary network access), write-blocking behavior based on server flags, response handling (even non-OK responses are returned for lexware.request), and file upload precautions (never inline bytes; use contentPath). This goes far beyond minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured and front-loaded: purpose, then search guidance, sandbox constraints, type definitions, and examples. Every section earns its place, though the extensive TypeScript type declarations make it denser than typical. It is appropriately sized for a code-execution tool, but less concise than shorter counterparts.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of an output schema, the description is nearly complete. It covers sandbox restrictions, write permissions, request/response shapes, and provides examples illustrating expected return patterns. However, it does not explicitly state that the arrow function's return value becomes the tool's output, nor does it mention execution timeouts or error handling for thrown exceptions, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes both parameters with 100% coverage. The description adds substantial meaning for the 'code' parameter by defining the available globals (lexware, spec), request/response types, multipart rules, and two complete examples. It does not add much for maxRequests beyond the schema's description, but the code semantics are richly enhanced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Execute a constrained Lexware Office API workflow by running a JavaScript async arrow function,' specifying a clear verb, resource, and mechanism. It distinguishes from siblings by explicitly directing users to 'search first when you need endpoint/domain guidance,' clarifying that this tool executes rather than explores.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use search first when you need endpoint/domain guidance; do not guess Lexware paths from memory.' This not only tells when to use the tool but also names the alternative (search) and the condition for switching. It further clarifies constraints like read-only defaults and checking spec.info.writesEnabled before writes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

match_bank_csv_to_vouchersA

Parses a bank statement CSV (date + EUR amount columns) and matches each transaction against Lexware vouchers by exact amount and a date-tolerance window. Fetches the voucher list itself (paginated, date-range padded by the tolerance). Narrow voucherType/voucherStatus (comma-separated, e.g. "purchaseinvoice" + "open,paid") when reconciling a specific category — the underlying /voucherlist endpoint refuses to traverse beyond 10,000 matching entries, so split by date range or narrow the filters if that happens.

ParametersJSON Schema
NameRequiredDescriptionDefault
csvContentYesRaw bank statement CSV content
voucherTypeNoComma-separated types (e.g. salesinvoice, purchaseinvoice, invoice, creditnote) or the wildcard "any". Defaults to "any".
voucherStatusNoComma-separated statuses (e.g. open, paid, voided, transferred, draft) or the wildcard "any". Defaults to "any".
dateToleranceDaysNo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses key behaviors: it fetches the voucher list itself (paginated, date-range padded), matches by exact amount and tolerance, and highlights the /voucherlist endpoint's traversal limit. This goes beyond a simple 'matches transactions' and gives valuable operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences convey the entire purpose without filler. The first sentence front-loads the primary function, and the second adds crucial edge-case behavior. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description covers the input format, matching logic, self-fetching behavior, pagination, and the 10,000-entry limit with a mitigation strategy. It does not explicitly state the output format, but for a matching tool this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes voucherType, voucherStatus, and csvContent (75% coverage). The description adds meaning beyond the schema by specifying that csvContent must contain date and EUR amount columns, and clarifies the date-tolerance window concept. Some parameter details are still left to the reader.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool parses a bank statement CSV and matches transactions against Lexware vouchers using exact amount and date-tolerance criteria. It distinguishes from siblings like match_receipts_to_bank_csv by specifying the bank CSV + voucher matching focus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides practical guidance on narrowing voucherType/voucherStatus for specific categories and warns about the 10,000-entry limit with a split-by-date-range workaround. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

match_receipts_to_bank_csvA

Matches receipt PDFs against a bank statement CSV (date + EUR amount) by extracting amount/date from each PDF's text and comparing with exact-amount + date-tolerance matching. Extraction is a best-effort regex heuristic — always review the 'unmatched' and 'extractionIssues' lists, don't assume completeness (no OCR: receipts that are pure scanned images without a text layer will not extract).

ParametersJSON Schema
NameRequiredDescriptionDefault
receiptsYes
csvContentYesRaw bank statement CSV content
dateToleranceDaysNo

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description takes on full disclosure and does well, warning about best-effort regex extraction, no OCR for scanned images, and the need to review 'unmatched' and 'extractionIssues' lists. It does not detail the output structure, but the key limitations are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, followed by concise caveats. Every phrase earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema or annotations, but the description covers the algorithm, expected inputs, and limitations. It mentions returning 'unmatched' and 'extractionIssues' lists but does not describe the full return shape or the meaning of date-tolerance beyond high level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33%, so the description must compensate. It adds context about CSV content (date + EUR amount) and matching logic, but it does not explicitly map parameters like dateToleranceDays to its behavior, leaving partial gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool matches receipt PDFs against a bank statement CSV by extracting amount/date and comparing with exact-amount/date-tolerance matching. It is specific about inputs and behavior, though it does not explicitly distinguish itself from sibling tool match_bank_csv_to_vouchers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool instead of match_bank_csv_to_vouchers or other siblings. The description explains what it does but lacks exclusions or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv2.0.0
    • First observedexecute
    • First observedmatch_bank_csv_to_vouchers
    • First observedmatch_receipts_to_bank_csv
    • First observedsearch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation4/5

The two match tools are distinct (bank CSV to vouchers vs. receipts to bank CSV) but share a similar 'match_*' prefix that could cause confusion. Search and execute are clearly separated for discovery vs. action, so overall boundaries are clear.

Naming Consistency5/5

All tool names use lowercase snake_case with a clear verb prefix: match_bank_csv_to_vouchers, match_receipts_to_bank_csv, search, execute. The pattern is consistent and predictable.

Tool Count5/5

With 4 tools, the server is well-scoped: two specialized matching helpers plus the essential search/execute pair for generic API access. No bloat and no obvious missing generic capability.

Completeness5/5

The generic execute tool wraps the entire Lexware API, covering any conceivable operation, while search provides full discovery. The two match tools cover specific reconciliation needs. Together they form a complete surface for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • buchpilot-mcp

    makririch
    F
    license
    B
    quality
    D
    maintenance
    MCP server for DACH accounting automation. Connect AI assistants to sevDesk and Lexoffice — create invoices, manage contacts, handle bookings and vouchers for German-speaking businesses.
    15
    27
    -

  • lexware-mcp-server

    lazyants
    A
    license
    B
    quality
    A
    maintenance
    MCP server for the Lexware Office API that enables management of invoices, contacts, articles, vouchers, and more through the Model Context Protocol.
    66
    298
    6
    Functional Source , Version 1.1, MIT Future

  • AbraFlexi MCP Server

    VitexSoftware
    A
    license
    B
    quality
    A
    maintenance
    Provides a comprehensive MCP interface to the AbraFlexi ERP REST API, enabling management of invoices, contacts, products, bank transactions, and other evidence through natural language.
    68
    1
    MIT

  • Lexware Office MCP Server

    bdiaby1
    A
    license
    A
    quality
    B
    maintenance
    MCP server for Lexware Office that enables querying and managing contacts, sales documents, vouchers, files, payments, and webhooks through a sandboxed two-tool interface (search/execute) with read-only-by-default write safety.
    2
    MIT