benethos-lexware-office-mcp

非公式 Lexware Office MCP サーバー

免責事項

• このプロジェクトは、Lexware または Haufe-Lexware GmbH & Co. KG とは提携、承認、後援関係にありません。「Lexware」と「Lexware Office」は、それぞれの所有者の商標です。
• このプロジェクトでは、ユーザー自身が生成し、いつでも失効できる API キーを使用して、公開されている仕様書に記載された API を利用します。この API の使用には Lexware 独自の利用規約が適用されます。この規約への同意は、本プロジェクトとは独立して行う必要があります。API は予告なく変更される場合があり、リクエストがレート制限されたり、ブロックされたりする可能性があります。
• このプロジェクトは実際の会計記録にアクセスします。書き込みアクセスはデフォルトで無効です。有効にした場合、API を通じて作成されるものはすべて、実在し法的効力を持つ記録です。確定済みの書類は、API を通じて取り消すことができません。
• データが不完全であったり、古くなっていたりする可能性があります。ここに記載された内容は、税務、会計、法律に関する助言ではありません。 税務申告、監査、記帳義務において、この内容に依拠しないでください。
• 本ソフトウェアは保証なしの「現状のまま」で提供されます。個人および業務での利用を想定していますが、利用は自己責任で行ってください。LICENSE をご覧ください。
• 商用利用の場合は、Lexware の API 利用規約と、利用者自身に課されるデータ保持および文書化の義務を確認してください。

目次

• このサーバーの目的
• 安全性を第一に
• 仕組み
• ツール
• 要件
• API キーの取得
• インストール
  • Claude Desktop 拡張機能として
  • uvx を使用する場合（任意の MCP クライアント向け）
• ブラウザーでの設定
• 個別のツールを無効にする
• 設定
  • 値の取得元と優先順位
  • ファイルの命名
  • 設定項目
• トランスポート
• コンテナーでの実行
  • Compose を使用する
  • 単一コンテナーとして実行する
  • 使い終わったらインターフェイスをオフにする
• ログ
• プロンプトの例
• レート制限
• 開発
• ライセンス
• 商標と関係

MCP クライアントを Lexware Office アカウントに接続する MCP サーバーです。Claude Desktop などのクライアントから、 公式の 公開 REST API を通じて接続します。請求書、 連絡先、商品、領収書について自然な言葉で質問すると、クライアントが取得します。

ステータス：0.6.2。 このサーバーは連絡先、領収書、書類を扱います。検索、読み取り、作成、変更、未払いの確認、 PDF のダウンロード、領収書のアップロードと記帳ができます。get_profile を使うと、 接続中のアカウントを確認できます。以下の表にあるすべてのツールを実装済みで、各ツールを 実際のアカウントで動作確認しています。起動元のクライアントとは stdio で通信し、 Claude Desktop 拡張機能または PyPI 経由で利用できます。また、別のシステムから接続する 必要がある場合は、ベアラートークンを使用したストリーミング可能な HTTP に対応します。 公開済みのコンテナーイメージに加え、実行用とチェックアウトからのビルド用の Compose ファイルも用意しています。詳しい技術仕様とロードマップについては、 SPECS.md を ご覧ください。

このサーバーの目的

Lexware Office は、小規模事業者の日々の会計業務を支えています。会計に関する質問の多くは、 未払いのものは何か、この顧客は何を注文したか、この経費に対応する領収書はどれか、といった 情報の読み取りに関するものです。アシスタントはデータを参照できれば、こうした質問に的確に 答えられます。このサーバーは、アカウント所有者が発行して取り消せる API キーを使い、 データをエクスポートすることなく、それを可能にします。

安全を最優先に

このサーバーは実際の会計システムに接続するため、デフォルト設定は慎重にしています。

理由がない限り、読み取り専用で実行してください。 このサーバーは実際の会計記録を変更できます。連絡先の作成、伝票の記録、請求書の発行、領収書の添付などが可能です。そして、そのようなツールをいつ呼び出すかを決めるのは、あなたではなくアシスタントです。--tools read-only を指定すれば、帳簿についての質問に答えるのに必要な機能がすべて使えます。多くの人が求めるのは、検索、閲覧、ダウンロードです。この設定では何も書き込みません。

書き込みツールを有効にするのは、そのツールを使う作業があり、実行後に何が残るかを把握している場合にしてください。この API では帳簿の伝票を削除できないため、誤った伝票はここで取り消すのではなく、ウェブアプリで修正します。また、確定済みの請求書は、使用済みの番号が付いた実際の書類です。必要なツールが分からない場合は、読み取り専用から始めるのが適切です。権限ページで後からワンクリックでツールを追加できます。また、Claude Desktop のように notifications/tools/list_changed に対応しているクライアントなら、再起動せずに変更が反映されます。

• 明示的に指定するまで、何も有効になりません。 新規インストールにはポリシーファイルがなく、ポリシーファイルのないサーバーはツールを一切提供しません。このサーバーが実行できることは、誰かが決めた結果であり、意図せず適用されたデフォルト設定ではありません。
• 各ツールは個別のフラグで設定します。 --tools を使って JSON ファイルに記述するか、setup でチェックを付けるか、手動で編集します。レベル単位でもグループ単位でもありません。create_contact を有効にして upload_file を無効にするのは一般的な設定であり、このファイルではどの組み合わせも指定できます。
• ツールによるコストは、判断時に確認できます。 有効になっているツールは、リクエストのたびにアシスタントに送られます。権限ページには、その数が各行に表示されます。
• ファイルは、ツール一覧の作成時と呼び出しの受信時に、2 回チェックされます。そのため、クライアント側の古いツール一覧を使っても、このチェックを回避することはできません。
• API キーがログに記録されたり、ツールの結果として返されたりすることはなく、エラーメッセージからも除去されます。API キーは .env だけに保存してください。 クライアントの設定ファイルなど、他の場所には保存しないでください。この設定ファイルは別のプログラムが管理して書き換えるものであり、助けを求めるときにスクリーンショットに撮られがちなファイルでもあります。また、あなたのマシン上のパスがアシスタントに渡されることもありません。

仕組み

クライアントはサーバーを起動するか、HTTP 経由でサーバーに接続し、MCP で通信します。モデルが実行できる操作は、Lexware にアクセスする前に決まります。ポリシーファイルに指定されていないツールはクライアントから利用できず、許可されたすべての呼び出しは、1 つのレートリミッターを備えた単一の API クライアントを経由します。API キーと権限は、setup が書き込む 2 つのファイルに保存されます。この独立したプロセスは、クライアントのプロンプト Set up Lexware Office から起動できます。また、ターミナルで benethos-lexware-office-mcp setup を実行して起動することもできます。

ツール

以下のツールはすべて実装済みで、実際のアカウントで動作確認済みです。ポリシーファイルに指定するまで、どのツールも有効になりません。

読み取りツール：

ツール	機能
get_profile	会社情報と接続確認
search_contacts	名前、メールアドレス、番号、役割で顧客や仕入先を検索します
get_contact	住所、役割、バージョンを含む1件の連絡先を取得します
search_articles	品番、バーコード、種類で絞り込んで商品を一覧表示します。API ではタイトルで検索できません
get_article	価格情報とバージョンを含む1件の商品を取得します
search_vouchers	中心となる検索機能です。種類、ステータス、連絡先、書類番号、期間、未決済分で伝票一覧を絞り込みます
get_sales_document	請求書、見積書、クレジットノート、注文確認書、納品書、督促状、前受金請求書をすべて読み取ります
get_voucher	ID または書類番号で帳簿伝票を読み取ります
get_payments	伝票の支払い状況と未決済金額を取得します
get_recurring_templates	定期的に請求書を発行するテンプレートを、1件またはページ単位で取得します
get_master_data	国、支払条件、記帳カテゴリ、印刷レイアウトを取得します。検索して絞り込むこともできます
download_document	販売書類のレンダリング済み PDF または XML を保存します
download_file	アップロードされた領収書など、保存済みファイルを保存します
read_download	リソースリンクをたどれないクライアント向けに、ダウンロードしたファイルを回答に含めます
get_deeplink	API を呼び出さずに、Web アプリ内の販売書類、連絡先、伝票へのパーマリンクを作成します

書き込みツールです。実際の会計記録を変更するため、変更されても問題のないアカウントに対して、一度に1つずつ有効にしてください。

ツール	機能
create_contact	顧客または仕入先を作成します
update_contact	指定していない項目には触れずに、連絡先を変更します
create_article	商品カタログに商品を追加します
update_article	指定していない項目には触れずに、商品を変更します
create_voucher	帳簿伝票を記録します
update_voucher	すでに記録されている伝票を変更するか、upload_file が未確認のまま残した領収書を記帳します
create_sales_document	請求書、見積書、クレジットノート、注文確認書、納品書、督促状を作成します。発行を依頼しない限り下書きとなり、アシスタントが発行できるのは明示的に指示された場合のみです
upload_file	パスまたは URL から領収書をアップロードし、伝票も作成します
attach_file_to_voucher	既存の伝票にファイルを添付します

update_contact と update_voucher は、API 呼び出しを1回ではなく2回行います。 API はレコードにパッチを適用せず置き換えるため、まず現在のレコードを読み取り、その上に変更を加えます。そうしないと、メールアドレスだけを変更した場合でも、住所、メモなど他のすべての情報が消えてしまいます。また、最後に読み取った version も必要です。その間にレコードが変更されていた場合、更新は拒否され、何も書き込まれません。

削除できるツールは1つだけです。

ツール	機能
delete_article	商品を削除します。API では元に戻せません。confirm: true が必要で、これがない場合は何も送信しません

これまでのところ、これは --tools irreversible ステップに含まれる唯一のツールで、そのステップだけで有効にできます。この API で削除できるのも商品だけであり、これも重要な点です。

--tools write は、取り消し可能という意味ではありません。このプリセットで有効になるツールはどれもレコードを削除しませんが、そのうち5つは作成したレコードをこの API では後から削除できません。create_contact で作成した連絡先を削除できるのは Web アプリだけです。また、create_voucher、create_sales_document、upload_file、attach_file_to_voucher は帳簿記録を残します。 API 経由では、帳簿伝票を削除できません。 削除用のエンドポイントがないため、誤った create_voucher は Lexware Office のウェブアプリで修正する必要があります。また、作成した時点で記帳されます。API では、作成時にステータスを指定できません。同じことは upload_file にも当てはまります。領収書をアップロードすると、それに対応する伝票も作成されるため、名前にはファイルしか記載されていなくても記録が残ります。この伝票は未確認の状態で作成され、update_voucher で内容を入力し、指定すれば記帳できます。

ダウンロードしたファイルは、サーバーを実行しているマシン上のダウンロードディレクトリに保存され、2 つの方法で報告されます。クライアントとサーバーが同じマシンを共有している場合に使う パス と、サーバーがどこにあってもクライアントがバイト列を取得できる リソース URI です。ファイル自体がツールの結果に含まれることはありません。base64 にするとコンテキストでファイルサイズのおよそ 1.37 倍を消費し、モデルはそもそも PDF を読み取れないからです。既存のファイルが置き換えられることもありません。すでにあるファイルと同一のダウンロードはそれを再利用し、異なるファイルは名前に連番を付けて隣に保存します。

ダウンロードディレクトリには、直近 100 件のドキュメントがキャッシュされます。古いダウンロードはサーバー起動時と各ダウンロード後に削除されます。すべてのドキュメントは Lexware Office に残っていて、1 回の呼び出しで取得できるからです。LXO_MCP_KEPT_DOWNLOADS で件数を変更でき、0 にするとすべて保持されます。LXO_MCP_DOWNLOAD_DIR で自分で指定したディレクトリは、同じ場所で設定しない限りそのまま残ります。設定した場合も、ダウンロードと同じ命名規則のファイルだけが削除されます。名前にスペースやウムラウトが含まれるファイルや、.docx などの拡張子を持つファイルは削除対象になりません。リソース一覧はクライアントから要求されるたびにディレクトリから読み込まれ、同じ最新のダウンロードが表示されます。また、サーバーを再起動しても保持されます。新しいダウンロードがあると、ツール一覧に変更があった場合と同様に、サーバーは notifications/resources/list_changed を送信します。これにより、ダウンロード一覧を一度取得したクライアントは、セッション開始時の一覧を使い続けず、再度取得できます。再取得するかどうかはクライアント次第です。

リソース一覧はプロンプトの一部ではありません。 ツール一覧はリクエストごとにモデルへ送られます。一方、リソース一覧が送られるのはクライアントが要求した場合のみで、それをどう扱うかはクライアント次第です。Claude Desktop では、サーバーの 追加元 メニューに表示され、誰かがファイルを選ぶと会話に追加されます。クライアントが一覧全体をモデルに渡す場合は、代わりにその分のコストがかかります。一覧の各項目には lexware:// URI、ファイル名、種類、サイズが含まれます。このマシンのパスは含まれません。各項目は約 230 文字なので、デフォルトの 100 件では約 23,000 文字、およそ 6,000～7,000 トークンになります。このようなクライアントでは、LXO_MCP_KEPT_DOWNLOADS の値を小さくすると、一覧とキャッシュの両方を縮小できます。

Claude Desktop はリソースリンクをまったくたどらないため、確実に使える方法は read_download です。同じ URI を受け取り、内容を回答に含めます。ファイルの種類によって、返される内容は異なります。

ファイル	返される形式
XML	テキスト。XRechnung を実際に読み取れます
PDF	各ページの画像。デフォルトでは最初の 10 ページ
画像	画像
その他	クライアントが処理する埋め込みバイナリ

PDF をそのまま渡すのではなくレンダリングするのは、Claude Desktop が API を呼び出す際に、埋め込みバイナリを画像ブロックに変換するためです。また、そこで許可されている画像タイプに application/pdf は含まれないため、リクエスト全体が拒否されます。ファイルはすでにサーバー上にあるため、レンダリングに API 呼び出しはかかりません。

ウェブアプリへのリンクは、別のツールです。get_deeplink は ID をブラウザー用の URL に変換します。API 呼び出しのコストはかからず、クライアントがファイルもリソースリンクも表示できない場合でも使えます。利用者が自分でリンクを開きます。ダウンロードにはリンクが含まれません。ダウンロードが返すのはバイト列の場所であり、これは別の情報だからです。かつて両者がひとまとめになったときは、使えるダウンロードに壊れたリンクが付いてくることがありました。 upload_file と attach_file_to_voucher は source を受け取ります。これは、サーバーが実行されているマシン上のパス、またはファイルの取得元となる URL です。どちらの場合も、PDF、JPEG、PNG、XML を受け付けます。ファイルごとの上限は 5 MiB で、API の仕様に準じます。XML ファイルは XRechnung として扱われ、それ以外の場合は拒否されます。

パスはモデルが選択します。 LXO_MCP_UPLOAD_DIR を設定しない場合、upload_file と attach_file_to_voucher は、このプロセスが読み取り可能なファイルのうち、いずれかの拡張子を持つファイルをすべて読み取り、Lexware に送信します。これにはあらゆる .xml ファイルが含まれ、設定ファイルやエクスポートファイルは、XRechnung ではないとして拒否される前に API に到達します。設定先をレシート用の受信フォルダーなど、1 つのディレクトリにすると、リンクも含め、その外にあるものは何も読み取られません。

URL は許可したアドレスからのみ取得されます。 別のサーバーから、添付ファイルのメールボックスサーバーなどが、ファイルへの有効期限付きリンクをモデルに渡すことがあります。その場合、ファイルはモデルを経由せず、そのサーバーから Lexware に送られます。LXO_MCP_UPLOAD_URLS には、そのようなリンクの送信先として許可するアドレスを、カンマ区切りで指定します。たとえば、スキームとホストに、任意でポートとパスの先頭部分を加えた https://files.example.com/inbox/ のような形式です。これを設定しない場合、URL は取得されません。 モデルが URL を選択し、メールを読み取るため、このリストは必須です。メッセージに隠された指示があると、何も対策をしなければ、モデルはサーバーに到達可能なあらゆる場所からファイルを取得させることができ、自社ネットワーク上のドキュメントサーバーも含まれ、取得したファイルを帳簿に登録できてしまいます。どのプレフィックスにも一致しないリンクは、何も送信される前に拒否されます。リダイレクトは追跡されず、取得には 30 秒の制限があり、ファイルは 5 MiB で打ち切られます。非圧縮での取得を要求し、空のファイルは拒否されます。また、プロキシの背後にある場合、このマシン上のサービスにはプロキシ経由では到達できないため、直接アクセスします。メールの添付ファイルによくあるように、バイト列のみ、application/octet-stream、またはタイプ指定なしで提供されたファイルは、先頭のバイトから形式を判定し、4 種類のいずれかの場合にのみ受け付けます。Lexware のキーが送信されることはありません。また、署名付きリンクのキーが含まれるパスやクエリは記録せず、ログにはリンクのホスト名のみを記録します。

各項目はパターンではなく URL プレフィックスです。 リンクがいずれかのプレフィックスで始まる場合に取得されます。スキームとホストは完全に一致し、ポートも一致する必要があります。ポートを指定しない場合、https では 443、http では 80 になります。パスはプレフィックスと同じか、その配下である必要があります。その後に続く部分、つまりパスの残りや署名付きリンクのクエリは任意です。https://files.example.com/inbox/ の場合：

• https://files.example.com/inbox/9f3c?sig=abc は取得されます
• https://files.example.com/outbox/9f3c は別のパスなので取得されません
• https://files.example.com.elsewhere.net/inbox/9f3c は別のホストなので取得されません
• https://files.example.com:8443/inbox/9f3c は別のポートなので取得されません

https://files.example.com/ を指定すると、そのホスト上のすべてのパスが許可されます。ワイルドカードはありません。ホストは常に完全な名前で記述し、* は存在しないホスト名として扱われるため、https://* では何も許可されません。

https:// が基本ルールです。http:// は同じマシン上のサービス向けで、127.0.0.1、::1、localhost のみ指定できます。ファイルが暗号化されずにネットワークを通過するため、それ以外のホストを指定するとサーバーは起動を拒否します。コンテナー内では、同じマシンとはコンテナーを指します。

要件

• uv。独自の Python と、以下のすべての例で使う uvx コマンドが付属しています。Claude Desktop 拡張機能には uv も Python も必要ありません。 Claude Desktop に両方が付属しています
• 独自の Python を使う場合は Python 3.11 以降。インストールすると、MCP SDK、httpx、platformdirs、PDF ページのレンダリングに使う pypdfium2、setup のページに使う Jinja2 がインストールされます
• 公開 API アドオンが有効になっている Lexware Office アカウント
• https://app.lexware.de/addons/public-api で取得した API キー

API キーの取得

1. アカウント所有者として Lexware Office にサインインします。
2. 公開 API アドオンを開きます。 https://app.lexware.de/addons/public-api
3. キーを作成して、一度だけコピーします。キーは一度しか表示されません。
4. バージョン管理に含まれるファイルには保存しないでください。setup はキーをサーバーが読み込む .env に書き込みます。保存先はユーザーごとの設定ディレクトリ、またはチェックアウトの場合は gitignore 対象の config/.env です。どちらの場所も、サーバーをどのディレクトリから起動しても検出されるため、Claude Desktop などのクライアントは設定ファイルに独自のキーを用意する必要がありません。環境変数を使うこともできます。

問題があるように見えた場合は、同じページでいつでもキーを無効にできます。アクセスを遮断する最も迅速な方法です。

インストール

方法は2つあります。Claude Desktop では、Claude Desktop 以外に何もインストールする必要のない拡張機能が最も簡単です。それ以外のクライアントで使う場合や、サーバーを自分で管理する場合は、uvx で実行してください。どちらも同じ設定を読み込むため、切り替えてもキーと権限はそのまま引き継がれます。代わりにコンテナーで実行する場合は、コンテナーでを参照してください。

このサーバーは公式 MCP Registryにも io.github.benethos-hub/benethos-lexware-office-mcp として登録されており、PyPI パッケージ、コンテナーイメージ、拡張機能の3つすべてが掲載されています。

Claude Desktop の拡張機能として

必要なのは、サインイン済みの Claude Desktop だけです。

1. API キーを取得します。 Lexware Office のアカウント所有者としてサインインし、 https://app.lexware.de/addons/public-api を開いてキーを作成し、すぐにコピーします。キーは一度しか表示されません。同じページからいつでも無効化できます。 API キーの取得を参照してください。

2. 拡張機能をダウンロードします。 このリンクから常に最新リリースをダウンロードできます： benethos-lexware-office-mcp.mcpb。

3. Claude Desktop の Settings → Extensions にドラッグします。 Claude Desktop は Python と uv を自動で用意するため、ほかにインストールするものはありません。

4. セットアップを開きます。 チャットでメッセージボックスのプラスをクリックし、 Connectors → Add from Unofficial Lexware Office MCP Server → Set up Lexware Office の順に選択します。ブラウザーが開き、 ブラウザーで設定するで説明しているインターフェイスが表示されます。これを選択できるのはユーザーだけで、モデルは選択できません。

5. キーを入力し、ツールを選択します。 キーは Zugangsdaten に入力し、ツールは Rechte でチェックを入れます。Beenden をクリックするとページが閉じます。どちらもすぐに反映され、Claude Desktop の再起動は不要です。

6. 試してみます。 "Which Lexware Office account are you connected to?" と尋ねます。 回答には、キーが属する会社が表示されます。

知っておくと便利なこと：

• 手順 5 までは失敗状態です。 インストール後は何も有効にならないため、セットアップページで保存するまでは、Claude Desktop にサーバーが失敗状態として表示され、ツールも提供されません。
• インストールダイアログでは何も求められません。拡張機能がコンピューター上のすべてにアクセスできるという警告が表示されますが、これはこのサーバーを含むすべてのローカル MCP サーバーに当てはまります。サーバーの依存関係は初回起動時にインストールされます。バージョンはこのプロジェクトのロックファイルに記載されているものです。
• セットアップページは 30 分間操作がないと自動的に終了します。
• 各リリースには専用のバンドルも添付されています。 特定のバージョンをインストールする場合は、ファイル名にバージョンが含まれているものを使用します。
• どちらか一方だけを使用してください。 拡張機能と、同じサーバーの claude_desktop_config.json 内のエントリーを併用すると、すべてのツールが二重に表示されます。拡張機能に切り替えるときは、そのエントリーを削除してください。
• 設定は共有されます。 拡張機能は、uvx を使ったインストールと同じユーザーごとの .env と tools.json を読み取るため、uvx benethos-lexware-office-mcp setup でも変更できます。
• 更新するには、 新しいファイルを古いファイルに上書きしてインストールします。Claude Desktop が置き換えられない場合は、先に Beenden でセットアップページを終了してください。ページの実行中は拡張機能のファイルが使用中になります。
• キーを変更した場合、 Claude Desktop をトレイから終了して再起動すると反映されます。最初のキーでは再起動は不要で、その再起動が済むまではキーを変更しても反映されません。
• Windows で試しました。 Microsoft Store 版の Claude Desktop を使用し、ほかには何もインストールしていません。macOS でも同様に動作する見込みですが、まだ試していません。

uvx を使う場合（すべての MCP クライアント向け）

ほかのクライアントで使う最も簡単な方法です。クローンも、手動での仮想環境作成も、git も不要です。uvx が PyPI からサーバーを取得し、必要に応じて実行します（benethos-lexware-office-mcp として公開されています）。

1. uv をインストールします。 まだの場合は、 uv のインストールページ で各プラットフォームの手順を確認してください。uvx も一緒にインストールされます。ここで必要なのはそれだけです。

2. サーバーを設定します。 インストールは不要です。uvx がパッケージを取得して実行します。

uvx benethos-lexware-office-mcp setup

すると、 ブラウザーで設定するで説明しているインターフェイスが開きます。キー、設定、ツールごとのチェックボックスがあります。すべて手動でも設定できます。uvx benethos-lexware-office-mcp --settings-sample > config/.env で設定ファイルを作成し、キーを入力して、以下で説明する --tools を使用してください。

動作を確認します：

uvx benethos-lexware-office-mcp --help

3. Claude Desktop の claude_desktop_config.json で接続先を指定します：

{
  "mcpServers": {
    "benethos-lexware-office-mcp": {
      "command": "uvx",
      "args": ["benethos-lexware-office-mcp"]
    }
  }
}

お使いのマシン上のパスはどこにも表示されていません。これがポイントです。uvx はパッケージ名で検索します。この設定について知っておくべきことが2つあります。

• 安定性のためにバージョンを固定します："args": ["benethos-lexware-office-mcp==0.6.2"]。 バージョンを固定しない場合、uvx は解決可能な最新リリースを使用するため、クライアントを再起動するだけで実行されるバージョンが変わる可能性があります。
• uvx はクライアントが使う PATH 上になければなりません。その PATH は、ターミナルのものと異なる場合があります。一部の GUI クライアントは、制限された環境変数を渡すためです。サーバーが起動しない場合は、command に uvx の絶対パスを指定し、クライアントを再読み込みするのではなく、完全に再起動してください。

独自のコマンドを使いたい場合は？ uv tool install benethos-lexware-office-mcp を実行すると、先頭に uvx を付けずに benethos-lexware-office-mcp を使えるようになります。コマンドラインから権限を頻繁に変更する場合は、導入する価値があります。それ以外に利点はありません。同じようにバージョンを固定でき、起動時間の差も数十ミリ秒です。知っておくべきことが1つあります。uv は独自のツールディレクトリにインストールしますが、新規インストール直後はそのディレクトリが PATH に含まれていません。インストール完了時にその旨が表示されます。uv tool update-shell を実行し、新しいターミナルを開いてください。

ソースから実行する場合は、開発時や未リリースのものを実行するときに使います。

git clone https://github.com/benethos-hub/lexware-office-mcp
cd lexware-office-mcp
uv sync
uv run benethos-lexware-office-mcp setup

クライアントには、そのチェックアウトの仮想環境のインタープリターが必要です。command には、Windows では .venv/Scripts/python.exe、それ以外では .venv/bin/python を指定し、args は ["-m", "benethos_lexware_office_mcp"] にします。

意図的にキーは記載していません。 サーバーは .env からキーを取得します。クライアントの設定ファイルは、認証情報を置く場所として適切ではありません。これは自分が所有するファイルではなく、別のプログラムが所有し、保存場所と書き換えのタイミングを決めます。MCP の設定について相談するときにスクリーンショットを撮られるファイルであり、クライアント自身の設定画面から読み取ることができ、クライアントのほかの設定と一緒に次のマシンへ移されます。少なくとも .env は、このプロジェクトが説明しているファイルであり、何かが代わりに同期することはなく、設定インターフェースからキーを表示せずに書き込めます。

この .env こそ、注意して扱うべきファイルです。稼働中の会計システムの認証情報が含まれているため、バージョン管理や共有フォルダーに入れず、ほかの人が読めるバックアップにも含めないでください。サーバーを使わなくなったら、ファイルを削除し、キーを取り消してください。アクセスを実際に終了させるには、キーの取り消しが唯一の方法です。

4. Claude Desktop を完全に再起動します — ウィンドウを閉じるのではなく、トレイから終了してください。クライアントは起動時に設定ファイルを一度だけ読み込むため、編集したファイルを反映するには再起動が必要です。.env の設定を変更した場合も同様です。サーバーも起動時に読み込むためです。権限の変更には再起動は不要です。あとから権限を変更すると、実行中のクライアントに通知されます。個別のツールをオフにするを参照してください。最初の API キーについても同様です。キーなしで起動したサーバーは、次の呼び出し以降に保存されたキーを使い、再起動されるまで呼び出しのたびにキーを読み込み直します。そのため、キーを変更するとすぐに反映されます。サーバーの起動時に設定していたキーを変更する場合は、再起動が必要です。

ブラウザーで設定する

uvx benethos-lexware-office-mcp setup

クライアントから設定することもできます。stdio 経由では、サーバーが Lexware Office のセットアップというプロンプトを提供しており、選択すると同じページが開きます。Claude Desktop では、メッセージボックスのプラスボタンを開き、サーバー名の下にある コネクター から選択します。この場合、モデルは起動できず、起動できるのはユーザーだけです。ページを開く以外の処理は行いません。この制限を設けているのはサーバーではなくクライアントです。一部のエージェントフレームワークやエディターのように、プロンプトをモデルに渡すクライアントでは、モデルもページを開けます。そのようなクライアントでは LXO_MCP_SETUP_PROMPT=0 を設定すると、プロンプトは表示されなくなります。 http://127.0.0.1:8771/ にある4つのページです。サイドバーの Beenden または Ctrl+C で終了します。ポートは HTTP トランスポートの 8770 より1つ大きいため、両方を同時に実行でき、--port で別のポートを指定できます。コマンドラインと同じファイルに書き込むため、どちらか一方でも両方でも使えます。Lexware Office はドイツ企業向けにのみ販売されているため、画面はドイツ語です。各ページは、以下に機能と角括弧内のラベルで示します。

概要（Übersicht）— インストールの状態を3行で表示します。保存済みか未設定かのキー、有効なツールの数とそのコスト、最後の接続テストの結果です。赤色の最初の行が次のステップを示し、右上のボタンからそのページに移動できます。その下には、クライアントに同じファイルを使わせるための "args" エントリーと、対象となるファイルおよびそれぞれがすでに存在するかどうかが表示されます。

認証情報（Zugangsdaten）— API キーは、特に指定しない限り、保存前に API で確認されます。その横には接続テストがあり、ボタンを押したときに1回だけ呼び出され、ページの読み込み時には実行されません。見つかったアカウントも表示されます。キーが再表示されたり、ログに記録されたり、エクスポートされたりすることはありません。環境変数でキーが設定されている場合は、その設定が保存した値より優先されるため、ページにその旨が表示されます。キーなしで起動したサーバーは、次の呼び出しからここに保存されたキーを使用し、再起動されるまで呼び出しのたびにここに保存されている値を読み込みます。サーバーの起動時に指定したキーを置き換える場合は、クライアントがサーバーを再起動した時点で反映されます。HTTP トランスポートのトークンは折りたたまれた項目の中にあり、サーバーがそのトランスポートに設定されている場合に開きます。

権限（Rechte）— ツールごとにチェックボックスが1つあり、グループ別に表示されます。プリセットはボタンで選択でき、保存ボタンはツールの数とともに右上にあります。ポリシーファイルがまだない新規インストールでは、初期設定として読み取りツールにあらかじめチェックが入っています。これはフォーム上の提案であり、権限が付与されたわけではありません。まだファイルはなく、そのため保存ボタンを押すまではツールもありません。ページにもその旨が表示されます。各行には、そのツールがアシスタントのコンテキストで消費する量が表示され、合計はチェック状態に応じて変わります。有効なツールはすべてリクエストのたびにモデルに送られるため、ツールを有効にすることは、権限の判断であると同時に予算の判断でもあります。書き込みツールには印が付き、API から取り消せない結果を生むツールには別の印が付きます。連絡先には nur App が付きます。Lexware Office では通知なく削除されるためです。記録簿に記載されるレコードには nur App · Buchhaltung が付きます。どちらも取り消せないという意味ではありません。作成時点では何も確定されず、ページの凡例には、後からレコードを確定させる4つの操作が示されています。

プロファイルもここで管理できます。現在の選択内容を名前を付けて保存し、後で読み込みます。読み込みでチェックボックスが更新されるだけで、保存ボタンを押すまでは tools.json に反映されません。すでに使われている名前は、既存の内容を黙って置き換えるのではなく拒否されます。大文字と小文字、空白の違いだけでは別のプロファイルになりません。既存のプロファイルを置き換える場合は、リストの横にある専用ボタンを使います。プロファイルはポリシーファイルと同じ場所にある tool_profiles.json に保存されます。

ポリシーファイルそのものは、同じページからダウンロードしたり読み込んだりできます。ファイルをそのまま扱うため、このインターフェースの有無にかかわらず別のインストール環境でも使えます。また、--tools で作成した tools.json もここで読み込めます。読み込んでもチェックボックスが更新されるだけで、保存は別途必要です。ファイルに記載されていないツールは無効のままで、その数がページに表示されます。これはコマンドラインで --tools sync を実行した場合と同じです。

設定（Einstellungen）— 機密情報ではない13個の設定を、接続、出力、ファイル、このページを開くプロンプトをクライアントに提示するかどうか、の4つのカードに分けて表示します。フィールドが空の場合は組み込みのデフォルト値が使われ、その値はプレースホルダーに表示されます。実際の環境変数によって設定されている項目は、保存しても何も変わらないため、編集欄ではなく値が表示されます。 知っておくとよいことが3つあります。起動するたびに起動コードが生成され、表示されるアドレスに含まれます。http://127.0.0.1:8771/?code=…。有効なコードがない場合、すべてのページに Code eingeben という入力欄が1つだけ表示されるため、同じマシン上の別のプログラムや別のユーザーが、ループバックポート経由でページを開くことはできません。コードはプロセスが動作している間有効で、コードを5回間違えると、それ以降の試行には毎回待ち時間が発生します。ブラウザーの setup では、1回だけ使える2つ目のコードでサインインします。これは、ブラウザーのアドレスがコマンドラインに表示され、同じマシンのほかのユーザーに読み取られる可能性があるためです。コードは暗号化されずに送信され、通信を読み取れる相手を締め出すことはできないため、127.0.0.1 にバインドします。コンテナーでは --host を使用できます。この場合、ホスト側でポートを公開してローカルに限定します。詳しくはコンテナー内での使用を参照してください。それ以外の場所でループバック以外にバインドすると、ポートにアクセスしてコードを読み取れる人なら誰でもページを開ける状態になり、起動時にその旨が表示されます。また、これは独立したコマンドです。MCP サーバーはHTTPを提供せず、Claude Desktopなどのクライアントが起動するのはそちらであり、このコマンドではありません。

--port N でポートを変更できます。--no-browser はアドレスを表示するだけです。リクエストがない状態がN分続くと終了する --exit-when-idle N は、プロンプトによって30に設定されています。--env-file と --tools-file では、編集するファイルを指定します。これらのファイルは、ほかの場合とは異なり、まだ存在していなくてもかまいません。--public-port N は、バインドするポートとは別のポートでコンテナーを公開するときに使用します。表示されて開かれるアドレスには、そのポートが記載されます。

クライアントが --tools-file を指定してサーバーを起動する場合は、setup にも同じ引数を指定してください。そうしないと、別のファイルが編集され、成功したと報告されます。両方のプロセスは起動時にファイルを確定し、その後は変更しません。また、互いがどのように起動されたかを知ることもできません。概要には、クライアントがインターフェースの参照するファイルと一致するようにするための "args" の行が表示されます。こちらのほうが簡単です。

個別のツールをオフにする

このサーバーが提供する内容を決めるのは、1 つの JSON ファイルだけです。他のものは一切関与しません。上の setup にあるボックスにチェックを入れるか、ファイルに次のコマンドを指定して開始します。

uvx benethos-lexware-office-mcp --tools read-only

これによりすべてのツールが tools.json に書き込まれ、指定したものはオン、残りはオフになり、実行内容も表示されます。3 つのプリセットがあり、それぞれ前のプリセットの内容を含みます。

	有効にするもの
--tools read-only	クエリのみ
--tools write	作成と更新も
--tools irreversible	記事の削除も
--tools sync	フラグは変更せず、ファイルにまだ記載されていないツールだけを追加

--tools show は報告のみを行います。--tools-file PATH で書き込み先を指定でき、どのプリセットでも使用できます。--tools write --tools-file ./tools.json のように指定すると、その場所にファイルが作成されます。

プリセットを使うとファイル全体が上書きされるため、手動での編集内容は失われます。プリセットはファイルを作成するときに使い、更新には使わないでください。アップグレードで新しいツールが追加されたら、--tools sync を実行します。新しいツールはオフの状態で追加され、設定したフラグはそのまま維持され、オンになるものはありません。このため、スクリプトから安全に実行できるのは、このコマンドだけです。

3 つ目の段階を独立させているのは、それ自体が個別の判断だからです。削除されたものは元に戻せないため、最も大きな選択肢を選ぶのではなく、削除対象を明示して選ぶべきです。そのような効果を持つツールは delete_article だけで、これは一時的な仕様ではありません。この API が削除できるのは記事だけです。また、後から確定や無効化はできません。後から予約できる唯一のものは、未確認のバウチャーです。アシスタントは update_voucher に finalize と confirm を渡す必要があり、あなたが依頼した場合にのみ実行できます。

--tools-file を指定しない場合、.env とまったく同じ順序で、優先度の低いものからファイルを検索します。

1. ユーザーごとの設定ディレクトリ
2. ソースから実行している場合は、チェックアウトの config/
3. 作業ディレクトリの config/、次にルートディレクトリ

最後に見つかったファイルが優先されます。まだ作成されていない場合は、最初の場所が使われます。その後、ファイルを編集します。

{
 "create_contact": false,
 "search_contacts": true,
 "upload_file": false
}

false に設定したツールは一覧に表示されず、呼び出すこともできません。ファイルに記載されていないツールもオフになります。何も記載しないことは拒否を意味するため、アップグレードで追加されたツールが勝手に表示されることはなく、あなたの指示を待ちます。ファイルがまったくない場合は、ツールも一切ありません。そのため、サーバーのセットアップには --tools が必要です。

ツール一覧を作成するときと、呼び出しのたびにファイルが読み込まれるため、編集内容は再起動なしですぐに反映され、オンにもオフにもできます。また、使用可能なツールのセットが変わると、サーバーはクライアントに通知します。クライアントは自動で一覧を再取得するため、Claude Desktop は実行中でも変更を反映します。どちらの場合も、オフにしたツールは呼び出せないため、クライアントに表示されている一覧に関係なく安全です。クライアントが変更を検知しない場合は、再起動してください。Claude Desktop の場合は、トレイから終了して再起動します。

各ツールには、その役割も宣言されています。読み取りか書き込みか、どのグループに属するか、また書き込んだ内容を削除できるかどうかです。この分類は --tools read-only の選択基準であり、ブラウザーインターフェースでのグループ分けや表示にも使われます。ただし、呼び出しの可否を決めるものではありません。決めるのはファイルだけです。

設定

値の取得元と、どの値が優先されるか

適用される .env は常に1つで、複数は適用されません。 次の場所が 優先度の低い順に検索され、最も優先度が高く、存在するものが対象のファイルになります。それ以外は 読み込まれません。

1. ユーザーごとの設定ディレクトリにある .env
2. サーバーの実行元となるチェックアウトがある場合は、その config/.env
3. 作業ディレクトリにある config/.env、続いて .env

--env-file を指定すると、そのファイルが使われ、検索は一切行われません。 これはポリシーファイルに対する --tools-file と同じルールで、どちらのフラグも「このファイルだけを使い、ほかは使わない」という意味です。

このファイルのほかに、次の2つがあります。1つは優先度が低く、もう1つは高くなります。

• 組み込みのデフォルト値。どのファイルにも記載されていない設定に適用されます。
• 実際の環境変数。ファイルに記載された値より優先されますが、空の場合は例外です。空の環境変数は未設定として扱われます。

最後の点は、意外に思われることがあります。シェルでエクスポートした設定、クライアントの env ブロックに記述した設定、または Compose ファイルで固定した設定は、.env を編集しても変更できません。手動で編集しても、setup を使っても同じです。値は書き込まれ、ファイルの内容も正しいのに、何も変わりません。

設定インターフェースでは、ユーザーが後から気づくのではなく、あらかじめそのことが分かるようにしています。各設定には取得元を示すバッジが付き、環境変数によって値が設定されている場合は、その旨が表示されます。保存した値が無視されているように見えるときは、そのバッジで理由が分かります。

コンテナでは、これは例外的なケースではありません。 Compose ファイルでは、コンテナ自体に属するトランスポート、バインドアドレス、ポート、許可するホストを、実際の環境変数として固定しています。それ以外の API キー、HTTP トークン、制限値などは設定ボリュームに任せているため、設定インターフェースから変更できます。

ポリシーファイルにも同じ優先順位が適用されます。また、LXO_MCP_TOOL_POLICY と --tools-file を使うと、ファイルを直接指定できます。インターフェースは起動時に検出したファイルを固定するため、ページ上の操作で、ページ自身が対象とするファイルを入れ替えることはできません。

ファイルの指定

--env-file PATH を指定すると、検索の代わりに設定ファイルを指定できます。--tools-file と組み合わせれば、クライアント設定の1つのエントリーに、個別のアカウントと権限を持たせられます。

"args": ["--env-file", "/path/to/test.env",
         "--tools-file", "/path/to/test-tools.json"]

存在しないパスを指定すると、検索に切り替えることなくエラーになります。ただし、ファイルを作成することも目的の1つである setup の場合は例外です。

setup を使うと、このファイルが書き込まれます。

設定

変数	意味	デフォルト
LXO_MCP_API_KEY	Lexware Office API キーです。必須です。可視 ASCII 文字のみ使用できます。スペースや、コピー時に混入した不可視文字がある場合は拒否されます	—
LXO_MCP_TOOL_POLICY	ツールごとのオン／オフ設定ファイルです。下記を参照してください	tools.json。.env と同じ方法で検索されます
LXO_MCP_BASE_URL	API のベース URL です。キーが送信されるため、https:// のみ使用できます	https://api.lexware.io
LXO_MCP_APP_BASE_URL	ディープリンク用の Web アプリのベース URL です。https:// のみ使用できます	https://app.lexware.de
LXO_MCP_DOWNLOAD_DIR	ダウンロードしたドキュメントの保存先です	ユーザーのキャッシュディレクトリ
LXO_MCP_KEPT_DOWNLOADS	ディレクトリに保持するダウンロード数です。新しいものから保持し、古いものは削除され、必要に応じて再取得されます。デフォルト以外のディレクトリを指定した場合にのみ有効です。0 はすべて保持します。リソース一覧には引き続き最新の 100 件が表示されます	未設定の場合、デフォルトディレクトリでは 100、指定したディレクトリではすべて
LXO_MCP_UPLOAD_DIR	アップロードツールが読み取り可能な唯一のディレクトリです	任意の場所
LXO_MCP_UPLOAD_URLS	アップロードツールがファイルを取得できる URL のプレフィックスです。カンマ区切りで指定し、ワイルドカードは使用できません。http:// は 127.0.0.1、::1、localhost に限り使用できます。これらはプロキシ HTTP_PROXY を介さずに取得されます	なし
LXO_MCP_TIMEOUT	HTTP タイムアウト（秒）です	30
LXO_MCP_RATE	すべてのエンドポイントに適用される、1 秒あたりのリクエスト数です	1.5
LXO_MCP_BURST	トークンバケットの容量です。アカウント自体のバケット容量は 4 です	2
LXO_MCP_PAGE_SIZE	検索でリクエストおよび返却されるページあたりの行数です	25
LXO_MCP_PDF_PAGES	read_download が PDF をレンダリングするデフォルトのページ数です。最大 100 ページです	10
LXO_MCP_LOG_LEVEL	このサーバー自身が stderr に出力するログのレベルです。基盤となるライブラリのレベルは WARNING のままです	INFO
LXO_MCP_SETUP_PROMPT	stdio 経由で Lexware Office をセットアップ プロンプトを提示します。0 にすると、プロンプトをモデルに渡すクライアント向けに提示を停止します	オン
LXO_MCP_TRANSPORT	stdio、streamable-http、または sse です	stdio
LXO_MCP_BEARER_TOKEN	すべての HTTP リクエストに必要な共有シークレットです。HTTP トランスポートでは必須です。可視 ASCII 文字のみ使用できます	—
LXO_MCP_HTTP_HOST	HTTP トランスポートでバインドするアドレスです	127.0.0.1
LXO_MCP_HTTP_PORT	バインドするポートです	8770
LXO_MCP_HTTP_PATH	トランスポートがサービスを提供する URL パスです	/mcp
LXO_MCP_ALLOWED_HOSTS	ループバック以外に許可する Host 値です。カンマ区切りで指定します	—
LXO_MCP_GENERATE_BEARER_TOKEN	トークンが設定されていない場合、起動時にトークンを生成し、設定ファイルに書き込みます	オフ
LXO_MCP_EXIT_ON_CONFIG_CHANGE	設定ファイルが変更されたときにプロセスを終了します。プロセスを再起動する仕組みで使用します	オフ

上記の設定はすべて使用されます。LXO_MCP_PAGE_SIZE は 250 に制限されています。これは、どのエンドポイントでも受け入れられる最小のページサイズです。これを超える値は、後で API エラーになるのではなく、起動時に拒否されます。search_articles は、指定値にかかわらず少なくとも 25 件を要求します。このエンドポイントはそれ未満の値を拒否するためです。

トランスポート

stdio がデフォルトで、Claude Desktop や同等のローカルクライアントが使用します。クライアントはサーバーを自身の子プロセスとして起動し、それ以外のものはサーバーと通信できません。

streamable-HTTP と SSE では、同じツールをポート上で提供します。コンテナや専用マシンで使用します。

uvx benethos-lexware-office-mcp --transport streamable-http --port 8770

このポートの前には、どちらも省略できないものが 2 つあります。すべてのリクエストに Authorization: Bearer <token> として含める必要があるベアラートークンです。LXO_MCP_BEARER_TOKEN が設定されていないと、サーバーは HTTP トランスポートでの起動を拒否します。そうしなければ、ポートにアクセスできる人なら誰でも Lexware の認証情報を使えてしまうためです。もう 1 つは SDK のDNS リバインディング対策です。Host と Origin をループバック名の許可リストと照合し、コンテナやプロキシによって別の名前が前面に置かれる場合は --allowed-hosts で拡張します。

どちらも、ポートをネットワーク上に公開して安全にするものではありません。ほかのプロセスと共有するマシン上で、ポートを耐えられる状態にするものです。--host はループバック以外の場所にバインドします。コンテナではこれが必要になりますが、見た目ほど安全性を緩和するものではありません。その理由についてはコンテナ内での実行を参照してください。

コンテナ内での実行

イメージは linux/amd64 と linux/arm64 向けに公開されているため、実行にこのリポジトリの内容は必要ありません。

docker pull ghcr.io/benethos-hub/benethos-lexware-office-mcp:latest

依存するものにはバージョンを固定してください。正確なリリースには :0.6.2、パッチリリースを追従するには :0.6 を指定します。:latest はリリースごとに更新され、:edge は main の内容からオンデマンドでビルドされるもので、リリースではありません。

イメージ名は、パッケージ名の変更に合わせて、0.2.0 以降のすべてのリリースで変更されています。 0.4.2 までは ghcr.io/benethos-hub/lexware-office-mcp として公開されていました。それ以前のリリースも同じダイジェストでコピーされているため、どちらの名前でも同じバイト列が取得されます。旧名では 0.4 のパッチリリースが公開されましたが、0.5.0 以降のリリースはありません。旧名で取得している場合は、上記の名前に変更してください。ボリュームはそのままで構いません。

Compose の場合

containers/production/ は公開済みイメージを実行し、このフォルダーだけで動作します。空の フォルダーで次を実行します。

mkdir lexware-office-mcp && cd lexware-office-mcp
for file in compose.yaml .env.example Caddyfile README.md; do
  curl -fsSL -o "$file" "https://raw.githubusercontent.com/benethos-hub/lexware-office-mcp/main/containers/production/$file"
done
cp .env.example .env                      # names the image's version
docker compose up -d                      # the server, on 127.0.0.1:8770
docker compose --profile setup up -d      # add the configuration interface
docker compose rm -f -s setup             # take the interface away again

docker compose --profile setup down は実行しないでください。 プロジェクト全体が停止し、サーバーも一緒に停止します。rm -f -s setup は該当するサービスだけを停止して削除し、サーバーは実行したままにします。docker compose stop setup でも同様に動作し、停止したコンテナーを次回のために残します。

更新するには、.env の LXO_VERSION を新しいバージョンに設定してから、docker compose pull && docker compose up -d を実行します。compose.yaml と同じ場所にある .env に含まれるのは、その設定、ホスト側のポート、HTTPS の設定だけです。サーバー独自の設定は設定ボリュームに保存されます。

ローカルネットワーク向けの HTTPS では、https プロファイルを使ってサーバーの前段に Caddy を配置します。COMPOSE_PROFILES=https を設定し、LXO_DOMAIN に名前を指定すると、別のマシンのクライアントからポート 443 の https://<name>/mcp にアクセスできます。証明書は Caddy 独自の CA が発行し、そのルート証明書は各クライアントで一度だけ信頼するよう設定します。Caddy が転送するのは MCP パスのみで、設定インターフェースは転送しません。手順については、このフォルダーの README をご覧ください。公開アドレス向けの用途ではありません。このサーバーが要求者を識別するために知っているのは、1 つのベアラートークンだけです。

以前は Compose ファイルがリポジトリのルートにありました。 チェックアウトからビルドしていました。containers/production/ は同じプロジェクト名を使うため、ボリュームに保存されたキー、トークン、ツールは引き継がれます。このフォルダーで docker compose up -d を実行すると、コンテナーを置き換えつつ、それらを保持します。チェックアウトからのビルドには containers/development/ を使用します。独自のプロジェクトで稼働中のインストールと並行して実行され、ポート 8780 と 8781 を使い、既存のボリュームには触れません。

Docker はサービスごとに最大 10 MB のログファイルを 5 つまで保持し、古いものから削除します。サーバーは拒否したリクエストごとに 1 行を記録し、受け取ったリクエストはすべて DEBUG レベルで記録します。そのため上限がなければ、アクセス可能なポートのログはコンテナーの稼働中ずっと増え続けます。

単一コンテナーの場合

docker run -d --name lexware-office-mcp \
  --restart unless-stopped \
  --log-opt max-size=10m --log-opt max-file=5 \
  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  -p 127.0.0.1:8770:8770 \
  -v lxo-config:/config -v lxo-downloads:/downloads \
  ghcr.io/benethos-hub/benethos-lexware-office-mcp:latest

自動生成されたトークンは設定ボリュームにあります。そこから次のように読み取れます。

docker exec lexware-office-mcp grep LXO_MCP_BEARER_TOKEN /config/.env

ファイル全体ではなく、その 1 行だけを表示します。キーを入力すると API キーも同じ場所に保存されるため、スクリーンショットを撮るかもしれないターミナルに表示する必要はありません。

設定インターフェースは、同じイメージの別のコマンドを同じボリュームに向けて実行します。

docker run --rm -d --name lexware-office-mcp-setup \
  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  -p 127.0.0.1:8771:8771 \
  -v lxo-config:/config -v lxo-downloads:/downloads \
  ghcr.io/benethos-hub/benethos-lexware-office-mcp:latest \
  setup --no-browser --host 0.0.0.0 --port 8771 \
        --env-file /config/.env --tools-file /config/tools.json

別のポートで公開する場合は、-p 127.0.0.1:9000:8771 に加えて --public-port 9000 を指定し、ログに出力されるアドレスに開くべきポートが表示されるようにします。

ログには開始コード付きのアドレスが表示されます。その行を開きます。

docker logs lexware-office-mcp-setup 2>&1 | grep "interface at"

--rm を指定して起動したため、停止するとコンテナーも削除されます。

docker stop lexware-office-mcp-setup

ここでの --restart unless-stopped は単なる飾りではありません。 設定ファイルが変更されるとコンテナーのプロセスが終了します。これにより、保存した設定が実行中のサーバーに反映されます。再起動ポリシーを指定しないと、プロセスは終了したままになります。

2 行目の残りの部分はセキュリティ強化の設定で、Compose ファイルでも同じです。 サーバーが書き込むのは 2 つのボリュームと /tmp だけなので、イメージ自体は読み取り専用にできます。また、1024 を超えるポートを使う一般ユーザーのプロセスに Linux のケイパビリティは必要ありません。

使い終わったらインターフェースを停止してください

Compose で docker compose logs setup を実行してログからアドレスを確認し、キーを入力してツールにチェックを入れたら、サイドバーの Beenden をクリックするか、以下のコマンドを使って停止してください。アドレスには公開されているポートが示されており、両方の Compose ファイルで LXO_SETUP_PORT を --public-port として渡しています。自動では停止しません。 このインターフェースは、平文で送られるコードの背後で API キーを受け付け、そのマシンが稼働している限り、ページを提供し続けます。 Beenden をクリックするとプロセスが終了し、停止したコンテナが残ります。このコンテナは docker compose rm -f -s setup で削除できます。docker run --rm で起動したコンテナは自動的に削除されます。

docker compose rm -f -s setup             # Compose
docker stop lexware-office-mcp-setup      # a single container
docker ps --filter name=setup             # nothing listed means it is off

サーバーは稼働し続けることを想定しています。インターフェースは設定作業をする数分間だけ稼働することを想定しているため、通常の docker compose up では起動せず、再起動ポリシーもありません。いったん停止すると、再度起動するまで停止したままです。

事前に準備しておくことはありません。 サーバーは初回起動時にベアラートークンを生成し、設定ボリュームに書き込んで、そのことを通知します。インターフェースに表示されるその値が、クライアントに必要な値です。イメージに埋め込まれているわけではないため、コピーごとに同じ値が共有されることはありません。

コンテナは 0.0.0.0 にバインドしますが、これはセキュリティを緩めるものではありません。 コンテナ内のループバックにあるプロセスには、公開ポート経由ではアクセスできません。分離を担うのはネットワーク名前空間であり、ポートにアクセスできる対象は、127.0.0.1 のみをマッピングするポート公開の設定で決まります。

ブラウザーで保存した設定は、稼働中のサーバーに反映されます。 設定は起動時に一度だけ読み込まれるため、設定ファイルが変更されるとコンテナを終了し、Compose が1秒後に再起動します。クライアントが開いているストリームによって終了が最大5秒遅れることがありますが、その後接続が閉じ、クライアントは新しいプロセスに再接続します。Compose が実際の環境変数として固定するトランスポート、バインドアドレス、ポート、許可ホストはコンテナに属し、ボリュームから変更できません。設定を参照してください。

ログ

すべて stderr に出力されます。INFO では、ツール呼び出しごとに1行記録します。読み取った内容または書き込んだ内容、Lexware ID、行数またはサイズ、API 呼び出し回数、所要時間が記録されます。拒否または失敗した呼び出しは、エラーのクラスを示す WARNING として記録されます。API による拒否の場合は、ステータスとエラーコードも記録されます。DEBUG では、API の試行ごとに1行、HTTP リクエストごとに1行が追加されます。ログレベルは LXO_MCP_LOG_LEVEL で設定します。

2026-09-30T13:58:50.597+02:00 INFO     tools: search_contacts read 12 rows in 1 API call, 230 ms

時刻はローカル時刻で、ミリ秒単位、タイムゾーンオフセット付きです。端末では、NO_COLOR が設定されていない限り、レベルとソースが色付きで表示されます。

ログの1行にも、アシスタントが送信した内容や API の応答内容は含まれません。検索語、名前、金額、ファイル名、クエリ文字列は記録されません。同じ理由から、基盤となるライブラリのログレベルも WARNING に設定されています。ライブラリの INFO ログには、リクエスト URL やエラー文が含まれるためです。設定インターフェースは保存した項目ごとに1行を記録しますが、キー、トークン、設定値は決して記録しません。

プロンプトの例

サーバーに接続したら、次のようなプロンプトでの利用を想定しています。

• 「未決済の請求書はどれですか。また、そのうち支払期限を過ぎているものはどれですか？」
• 「今四半期に Muster GmbH に請求した内容をすべて表示してください。」
• 「請求書 RE-2024-0142 の内容と、支払い済みかどうかを教えてください。」
• 「品番 A-1007 の商品を探して、現在の価格を教えてください。」
• 「最後に発行したクレジットノートの PDF をダウンロードしてください。」
• 「Lexware Office で伝票 X を開くリンクを教えてください。」

レート制限

Lexware API では、トークンバケットによって制御される、1 秒あたり 2 件のリクエストが許可されています。この上限はグローバルであり、API のすべてのエンドポイントに同時に適用されます。そのため、連絡先の読み取りと請求書の読み取りは、同じ枠を消費します。

サーバーはこれに合わせて、プロセス内のすべてのリクエストで共有する単一のトークンバケットを使用し、デフォルトではドキュメントに記載されたレートをわずかに下回る速度で補充します。Lexware によると、バッファーなしで制限を正確に適用しようとしても、ネットワークのジッターで到着時刻がずれると、結局 429 が発生しやすくなります。そのため、デフォルトでは余裕を持たせています。リクエストは並列に送信されず、このバケットを通じて順番に処理されるため、多くのドキュメントに関わる広範な質問では、ブロックされるのではなく処理が遅くなります。

知っておくべきことが 2 つあります。

• 上限はこのプロセスではなく、アカウントに適用されます。サーバーの 2 つ目のインスタンス、別の連携、または自分で実行するスクリプトも、すべて同じ 1 秒あたり 2 件の枠を消費します。
• Lexware は、429 の後もリクエストを繰り返し続けるクライアントが、恒久的にブロックされる可能性があると警告しています。そのため、サーバーは指数バックオフを行い、さらに強くリトライするのではなく、数回試行した後に断念します。

アカウントのバケットは 2026-08-21 に測定され、上限は4 件です。一度に 5 件のリクエストを送信したところ、4 件が通り、1 件が拒否されました。デフォルトの 2 では、Web アプリ、別の連携、サーバーの 2 つ目のインスタンスなど、同じアカウントを利用するほかのすべてのものに、その半分を残します。このサーバーだけが利用者だと分かっている場合に限り、4 に引き上げてください。

アカウントの動作が異なる場合は、LXO_MCP_RATE と LXO_MCP_BURST で両方のリミッター値を設定できます。

開発

uv sync --extra dev
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy

テストスイートは完全にオフラインで実行できます。HTTP レイヤーをモックし、API キーも必要としないため、どこでも実行できます。テストのうち 2 種類では、プロセスを終了させずに、マシン上で実際のサブプロセスとしてサーバーを起動します。3 つのテストでは stdio 経由でサーバーと MCP 通信を行います。これにより、起動時に stdout へ何も書き込まれないことも検証できます。また、設定インターフェイスは実際のループバック HTTP サーバーと Cookie jar を介して操作します。CSRF ガードは、ブラウザーからアクセスされる状況でテストしてこそ意味があるためです。

このリポジトリには API キーは含まれておらず、CI にもキーを設定しません。そのため、チェックアウトしただけで Lexware に接続されることはありません。したがって、実際の API に対するサーバーの確認は、必ず自分でキーを用意してローカルで意図的に実行するものであり、上記のテストスイートとは別で、その一部になることもありません。

uv run python live/smoke.py
uv run python live/smoke.py --env-file path/to/.env

このテストではアカウントを読み取りますが、書き込みは行いません。ビルドされるサーバーには read-only プリセットが設定されるため、書き込みツールは呼び出せる状態になりません。確認した内容、アカウントにデータがなかった項目、失敗した項目が出力され、レポートを共有できるよう、レコード ID はマスキングされます。pytest から実行されることはありません。実際の環境での確認が合格条件にならない理由については、SPECS.md のセクション 14.1 を参照してください。

コントリビューションや問題の報告を歓迎します。 設計上の決定と、その根拠および測定結果は SPECS.md に記録されています。

ライセンス

MIT。LICENSE を参照してください。

商標および提携関係

このプロジェクトは、Lexware、Haufe-Lexware GmbH & Co. KG、またはそれらの子会社の提携先、承認を受けた団体、スポンサーではありません。「Lexware」および「Lexware Office」は、それぞれの所有者の商標であり、このソフトウェアが連携する API の名称を説明する目的でのみ使用しています。

このソフトウェアは、アカウント所有者が提供し、いつでも無効にできる認証情報を用いて、ドキュメントに記載された公開 API のみと通信します。この API の利用には Lexware 独自の利用規約が適用され、このプロジェクトとは独立して同意する必要があります。