Lexware Office MCP Server

Lexware Office MCP 服务

适用于 Lexware Office（前身为 Lexoffice）的 MCP 服务。它让支持 MCP 的助手能够通过 Lexware Office 公共 API 查询和管理联系人、销售单据、凭证、文件、付款、Webhook 和参考数据。

该服务采用 Code Mode：不为每个 API 端点分别提供一个 MCP 工具，而是提供两个工具——search 用于探索精心整理的 Lexware API 目录，execute 用于运行受限的沙盒 API 工作流。这样既能精简工具集，又能覆盖整个 API，并可在单次调用中完成分页、聚合和多步骤报告。

从 1.x 升级？旧版的逐端点工具服务已在 2.0.0 中移除。请参阅 docs/guide.md#migrating-from-1x。

使用 contentPath 上传？现在必须配置 LEXWARE_OFFICE_UPLOAD_DIRS。请参阅 docs/guide.md#migrating-contentpath-requires-lexware_office_upload_dirs。

功能

• 广泛覆盖 Lexware Office API，支持读取和写入工作流
• 销售单据：发票、报价单、订单确认书、贷项通知单、送货单、催款通知和预付款发票
• 联系人管理：创建、读取和更新客户与供应商
• 簿记：凭证、记账类别、付款和文件上传
• 参考数据：个人资料、国家、打印布局、付款条件、定期模板
• Webhook：创建、列出、查看和删除事件订阅
• 默认只读：写入操作需要通过环境变量显式启用

工作原理

该服务提供两个 MCP 工具：

• search — 针对精心整理的 OpenAPI-lite Lexware 目录运行沙盒 JavaScript 异步箭头函数。
• execute — 运行沙盒 JavaScript 异步箭头函数，并提供一项宿主能力 lexware.request，用于调用相对路径 /v1/... 的 Lexware API。

两个工具都声明 MCP 注解（search 为只读；仅在启用写入时，execute 才标记为有破坏性），并在 JSON 文本块旁返回 structuredContent。基于 MCP TypeScript SDK v2 构建（协议修订版为 2026-07-28，并兼容 2025 年左右的客户端）。请参阅 docs/guide.md。

execute 调用示例：

async () => {
  const response = await lexware.request({
    method: 'GET',
    path: '/v1/contacts',
    query: { name: 'Muster', page: 0, size: 10 }
  });

  return response.data;
}

沙盒无法访问 Lexware API 密钥、Node 全局变量、文件系统、导入、fetch 或任意网络访问。lexware.request 只接受相对路径 /v1/...，并使用宿主进程中的 API 密钥发送请求。

execute 结果包含 requests，这是一份审计日志，每次 HTTP 尝试对应一条 { method, path, status, ok, error, write, sent, outcome, durationMs } 记录——即使执行失败也会包含，因此你可以查看哪些写入操作已经成功发送。如果某次写入的 error 不为空且 outcome: "unknown"，表示请求已发送但结果未知（已中止、超时、网络错误）——Lexware 可能已应用该操作，因此重试前请先通过 GET 检查。如果 GET 返回 429 且 Retry-After ≤ 5 s，则只要 30 s 执行时限允许，就会自动重试一次。取消工具调用（或达到 30 s 执行超时）会中止正在进行的 Lexware 请求。

安全处理二进制文件上传

上传通过带有 contentPath（宿主从磁盘读取本地文件）、contentBase64（二进制 FormData 部分）或 bodyBase64（原始二进制正文）的 multipart 部分实现二进制安全处理。宿主会在 QuickJS 沙盒之外读取或解码内容，并构建 Buffer / Blob 正文。

推荐使用 contentPath — 传入文件的绝对路径，而不是直接嵌入字节。需要设置 LEXWARE_OFFICE_ALLOW_WRITES=true（上传属于写入操作）和 LEXWARE_OFFICE_UPLOAD_DIRS（请参阅上传目录）；文件必须位于运行 MCP 服务的机器上：

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 };
}

有关详细信息和所有支持的模式，请参阅 docs/guide.md。

配置

获取 Lexware Office API 密钥

请在 https://app.lexoffice.de/addons/public-api 创建 API 密钥。

前提条件

• Node.js 22 或更高版本
• LEXWARE_OFFICE_API_KEY 环境变量

Claude Desktop / 使用 NPX 的 MCP 配置

推荐：使用打包好的服务

运行 GitHub 最新版本发布中的打包二进制文件（#semver:^3 会解析到此主版本的最新标签，并自动获取未来发布的版本）。此软件包会在 GitHub 安装期间通过 prepare 自行构建，因此用户无需克隆仓库或提交 build/ 构建产物。

{
  "mcpServers": {
    "lexware-office": {
      "command": "npx",
      "args": ["-y", "--package=github:JannikWempe/mcp-lexware-office#semver:^3", "lexware-office"],
      "env": {
        "LEXWARE_OFFICE_API_KEY": "YOUR_API_KEY_HERE",
        "LEXWARE_OFFICE_READ_ONLY": "true"
      }
    }
  }
}

故障排除： 如果上述 npx 命令在准备 Git 依赖项时失败，并出现提及 --before 的错误，你的 npm 用户配置中可能包含 minimum-release-age，这会与 npm 内部的 --before 标志冲突。可通过以下两种方式解决：

# Either bypass your user config for this invocation
NPM_CONFIG_USERCONFIG=/dev/null \
  npx -y --package=github:JannikWempe/mcp-lexware-office#semver:^3 lexware-office

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

此软件包发布到 npm 后，请将 GitHub 软件包规范替换为 npm 软件包名称：

"args": ["-y", "--package=mcp-lexware-office", "lexware-office"]

从 TypeScript 源码进行本地开发

本地开发时，可在克隆仓库并安装依赖项后，使用 tsx 直接运行 TypeScript 源码：

{
  "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"
      }
    }
  }
}

此源码配置仅用于开发。最终用户应优先使用上述打包二进制文件。

写入安全性

此服务默认只读。 除非明确选择启用，否则会阻止 POST、PUT、PATCH 和 DELETE 请求：

{
  "LEXWARE_OFFICE_ALLOW_WRITES": "true"
}

LEXWARE_OFFICE_READ_ONLY=true 是强制阻止设置，其优先级高于 ALLOW_WRITES=true：

{
  "LEXWARE_OFFICE_READ_ONLY": "true"
}

详细权限模型请参阅 docs/guide.md#permissions。

上传目录

除非 LEXWARE_OFFICE_UPLOAD_DIRS 列出服务可读取文件的目录，否则会禁用 multipart contentPath 上传（macOS/Linux 上以 : 分隔，Windows 上以 ; 分隔）：

{
  "LEXWARE_OFFICE_ALLOW_WRITES": "true",
  "LEXWARE_OFFICE_UPLOAD_DIRS": "/Users/me/Documents/Belege:/Users/me/Downloads"
}

文件必须在跟随符号链接后解析到这些目录之一内的路径，包括其子目录。其他路径一律拒绝。使用 contentBase64 上传时无需此设置。

Docker

构建镜像：

docker build -t mcp-lexware-office:latest .

运行：

docker run -i --rm \
  -e LEXWARE_OFFICE_API_KEY \
  -e LEXWARE_OFFICE_READ_ONLY=true \
  mcp-lexware-office:latest

contentPath 上传会从容器的文件系统读取：挂载卷并将 LEXWARE_OFFICE_UPLOAD_DIRS 设置为容器路径，然后传入 contentPath: '/data/receipt.pdf'：

docker run -i --rm \
  -e LEXWARE_OFFICE_API_KEY \
  -e LEXWARE_OFFICE_ALLOW_WRITES=true \
  -e LEXWARE_OFFICE_UPLOAD_DIRS=/data \
  -v /host/dir:/data:ro \
  mcp-lexware-office:latest

构建和测试

npm run build
npm test

文档

• 指南和迁移说明
• Lexware Office API 密钥设置

许可证

MIT。请参阅 LICENSE。