Lexware Office MCP Server

Lexware Office MCP サーバー

Lexware Office（旧称 Lexoffice）向けの MCP サーバーです。MCP 対応アシスタントから Lexware Office の公開 API を通じて、連絡先、販売書類、領収書、ファイル、支払い、Webhook、参照データを照会・管理できます。

このサーバーは Code Mode を使用します。API エンドポイントごとに MCP ツールを用意する代わりに、厳選された Lexware API カタログを探索する search と、制約付きのサンドボックス化された API ワークフローを実行する execute の 2 つのツールを公開します。これにより、ページネーション、集計、複数ステップのレポートを 1 回の呼び出しで処理しながら、ツールの種類を少なく保てます。

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：イベントサブスクリプションの作成、一覧表示、確認、削除
• デフォルトでは読み取り専用：書き込みには環境変数による明示的な許可が必要

仕組み

このサーバーは 2 つの MCP ツールを公開します。

• search — 厳選された OpenAPI-lite Lexware カタログに対して、サンドボックス化された JavaScript の非同期アロー関数を実行します。
• execute — lexware.request という 1 つのホスト機能を使用し、相対 /v1/... パスへの Lexware API 呼び出しを行う、サンドボックス化された JavaScript の非同期アロー関数を実行します。

どちらのツールも 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 で確認してください。429 と Retry-After が 5 秒以下で返された GET は、30 秒の実行時間内に収まる場合、自動的に 1 回再試行されます。ツール呼び出しをキャンセルした場合（または 30 秒の実行タイムアウトに達した場合）、実行中の 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 環境変数

NPX を使用した Claude Desktop / 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 フラグと競合します。解決方法は 2 つあります。

# 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 を参照してください。