lexware-php-mcp

English | Deutsch

Unofficial. Not affiliated with Haufe Group. Lexware and lexoffice are trademarks of Haufe Group.

lexware-php-mcp is an unofficial, read-only Model Context Protocol server for Lexware Office (formerly lexoffice), written in PHP on top of the official PHP MCP SDK.

Ask Claude things like "Which invoices are overdue?" and get answers straight from your account.

No PHP needed: for Claude Desktop on macOS and Windows there is a one-click extension, see Quick start.

Why a PHP server?

The existing Lexware MCP servers are written in TypeScript or Python. This one is the PHP-native option, and that is the point: it is not a claim that PHP is technically better, but that PHP shops should not need a second runtime to give an AI assistant access to their bookkeeping.

• One runtime you already run, or none at all. PHP 8.4 and Composer, nothing else. No Node.js or Python toolchain, no npx downloading code at startup. Without PHP, use the standalone download, which has PHP built in.

• Small enough to audit. The server has three runtime dependencies (mcp/sdk, symfony/http-client, symfony/clock) and a handful of classes. Anyone handing an AI access to accounting data can read all of it in an afternoon. It is checked with PHPStan level 8 including strict rules.

• Built for the German Mittelstand stack. Many agencies, freelancers and in-house IT teams around Lexware work in PHP (Symfony, Laravel, WordPress, Shopware). Tools are plain classes, so they can later move into a Symfony application via symfony/mcp-bundle (see ADR 0001).

• Lexware pitfalls handled, not left to you. Invoices written in Lexware and booked sales vouchers are two different voucher types; the server queries both. Lexware's 2 requests per second limit is throttled, and Lexware's error messages are passed through so a failure is explainable.

Related MCP server: lexware-mcp-server

Example questions

• Which invoices are overdue, and by how many days?

• Show open invoices for customer Müller, with totals per currency.

Status

v0.3.0, early but usable. See the changelog. Currently available tool:

Planned: voucher search, voucher detail with net amounts, contact search, revenue per period. See ADR 0001.

Safety

• Read-only. The server only sends GET requests; there are no tools that create or change data.

• The API key is read from the environment only and never appears in output or error messages.

• Bank details (IBAN, BIC, account data) are stripped from every response before it reaches the model.

• Requests are throttled to the Lexware limit of 2 per second, with retry and backoff on 429/5xx.

• Data returned by a tool is sent to the model provider of your MCP client (e.g. Anthropic for Claude Desktop). Only use it with accounts whose data you may share with that provider.

Found a security problem? Please report it privately, see SECURITY.md.

Use of the Lexware API is governed by the Public API Lizenz- und Nutzungsbedingungen.

Quick start: Claude Desktop, no PHP needed

You need a Lexware Office public API key: https://app.lexware.de/addons/public-api. Nothing else has to be installed; the download contains everything, PHP included.

1. Download the extension for your system from the latest release:

   • macOS (Apple silicon and Intel): lexware-php-mcp-macos.mcpb

   • Windows: lexware-php-mcp-windows.mcpb

2. Double-click the file. Claude Desktop opens and shows the extension. If double-clicking does not work, open Settings > Extensions > Advanced settings > Install Extension… in Claude Desktop and pick the file.

3. Click Install and paste your API key when asked. Claude Desktop stores it in its secure storage; it does not end up in a configuration file. Claude Desktop shows a warning before installing because the extension is not signed. Signing costs money for a certificate, which this free project does without; the code is open for review on GitHub. Confirm with Install.

4. Make sure the extension is switched on, then ask: "Which invoices are overdue?"

To update, download the new .mcpb and install it the same way.

The Windows extension is built and tested automatically (start-up and a TLS connection to the Lexware API), but the maintainer has not tried it on a Windows PC. Reports are welcome as an issue.

Standalone binary: Claude Code and other MCP clients

Every release also contains the server as a single executable file, again with PHP built in:

SHA256SUMS in the release lets you verify the download (shasum -a 256 -c SHA256SUMS --ignore-missing).

On macOS and Linux, make the file executable. The binaries are not signed, so on macOS also remove the download quarantine, otherwise Gatekeeper refuses to start the file:

chmod +x lexware-php-mcp-macos-arm64
xattr -d com.apple.quarantine lexware-php-mcp-macos-arm64   # macOS only

Register it with Claude Code:

claude mcp add --env LEXWARE_API_KEY=your-api-key lexware-php-mcp -- /absolute/path/to/lexware-php-mcp-macos-arm64

By default the entry applies to the current project only. Add --scope user to make it available everywhere. Check with claude mcp list, or run /mcp inside a session. The key is stored in plain text in Claude Code's configuration; keep it private.

Linux needs the usual CA certificates for HTTPS (package ca-certificates, installed on desktop systems anyway).

Installation from source (PHP developers)

If you already work with PHP, you can run the server from source instead.

Requirements:

• PHP 8.4 or newer (CLI) with ext-json

• Composer

git clone --branch v0.3.0 https://github.com/Stefan39/lexware-php-mcp.git
cd lexware-php-mcp
composer install --no-dev

To update later: git fetch --tags && git checkout <new-tag> && composer install --no-dev.

A lexware-php-mcp.phar is attached to every release as well; it runs with php lexware-php-mcp.phar.

Claude Desktop with a manual configuration

The extension above is the easier way. If you prefer to configure the server yourself, add one entry under mcpServers in claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

The file usually contains other settings already. Do not paste a second { ... } block at the end: add the "lexware-php-mcp" entry inside the existing "mcpServers" object, or create "mcpServers" as a new top-level key if it is missing. Check the result with python3 -m json.tool claude_desktop_config.json before restarting Claude Desktop.

macOS: API key from the Keychain

Store the key once; the command prompts for it, so it never ends up in your shell history:

security add-generic-password -s lexware-php-mcp -a lexware -w

Entry for mcpServers (adjust both paths; which php shows yours). With a standalone binary, replace /opt/homebrew/bin/php /absolute/path/to/lexware-php-mcp/bin/lexware-php-mcp by the path of the binary:

"lexware-php-mcp": {
  "command": "/bin/sh",
  "args": ["-c", "LEXWARE_API_KEY=$(security find-generic-password -s lexware-php-mcp -w) exec /opt/homebrew/bin/php /absolute/path/to/lexware-php-mcp/bin/lexware-php-mcp"]
}

Other systems: API key in the config

"lexware-php-mcp": {
  "command": "php",
  "args": ["/absolute/path/to/lexware-php-mcp/bin/lexware-php-mcp"],
  "env": {
    "LEXWARE_API_KEY": "your-api-key"
  }
}

The key is then stored in plain text in that file; keep it private.

Quit Claude Desktop completely, start it again and ask: "Which invoices are overdue?" If the server does not show up, check the log (macOS: ~/Library/Logs/Claude/mcp-server-lexware-php-mcp.log).

Claude Code from source

claude mcp add --env LEXWARE_API_KEY=your-api-key lexware-php-mcp -- php /absolute/path/to/lexware-php-mcp/bin/lexware-php-mcp

Configuration

Development

composer install
composer check   # php-cs-fixer (dry run), PHPStan level 8, PHPUnit
make cpd         # duplication check (needs Node/npx)

Debug the server interactively with the MCP Inspector. The Inspector starts the server with a minimal environment, so pass the key with -e; a variable set in your shell does not reach it:

npx @modelcontextprotocol/inspector -e LEXWARE_API_KEY=your-api-key php bin/lexware-php-mcp

Tests never touch the real API; they use Symfony's MockHttpClient and MockClock.

Standalone builds

The workflow .github/workflows/release.yml builds the PHAR (Box, config box.json), the static binaries (static-php-cli: PHP plus the PHAR in one file) and the Claude Desktop extensions (build-tools/package-mcpb.sh, manifest in build-tools/mcpb/). It runs on pull requests that touch the build, and on a version tag it attaches everything to a draft release. Check any build with build-tools/smoke-test.sh <command>; with SMOKE_TEST_TLS=1 it also sends one request with an invalid key to the real API and expects HTTP 401. Keep version in build-tools/mcpb/manifest.json in line with ServerFactory::VERSION (a test checks it).

License

MIT, see LICENSE.