Неофициальный Lexware Office MCP Server

Отказ от ответственности

• Этот проект не связан с Lexware или Haufe-Lexware GmbH & Co. KG, не одобрен и не спонсируется ими. «Lexware» и «Lexware Office» являются товарными знаками их соответствующих владельцев.

• Он использует документированный публичный API с ключом API, который вы генерируете и можете отозвать самостоятельно. Использование этого API регулируется собственными условиями Lexware, которые вы принимаете независимо от этого проекта. API может измениться в любое время, а запросы могут быть ограничены по частоте или заблокированы.

• Он обращается к реальным бухгалтерским записям. Запись по умолчанию отключена. Если вы её включите, всё, что создано через API, является реальной и юридически значимой записью — окончательный документ нельзя отозвать через API.

• Данные могут быть неполными или устаревшими. Ничто здесь не является налоговой, бухгалтерской или юридической консультацией. Не полагайтесь на это для отчётности, аудита или выполнения ваших обязанностей по ведению бухгалтерского учёта.

• Предоставляется «как есть», без гарантий. Предназначено для личного и профессионального использования на ваш собственный риск. См. LICENSE.

• Для коммерческого использования ознакомьтесь с условиями API Lexware и вашими собственными обязанностями по хранению и документированию.

Сервер MCP, который подключает MCP-клиент, такой как Claude Desktop, к учётной записи Lexware Office через официальный публичный REST API. Задавайте вопросы о счетах, контактах, товарах и ваучерах на простом языке, и клиент получит их для вас.

Статус: 0.2.2. Сервер работает с контактами, ваучерами и документами: находит их, читает, создаёт, изменяет, показывает, что ещё не оплачено, скачивает PDF и загружает квитанции. get_profile отвечает, какая учётная запись подключена. Каждый инструмент в таблице ниже реализован и был протестирован на реальной учётной записи. Он общается через stdio с клиентом, который его запускает, и через потоковый HTTP за bearer-токеном, когда до него должен добраться кто-то другой — в виде опубликованного образа контейнера, с файлом Compose для них обоих. См. SPECS.md для полной технической спецификации и дорожной карты.

Зачем это существует

Lexware Office хранит повседневную бухгалтерию малого бизнеса. Большинство вопросов о ней — это вопросы на чтение: что ещё не оплачено, что заказал этот клиент, какая квитанция относится к этому расходу — и именно на такие вопросы ассистент хорошо отвечает, когда видит данные. Этот сервер делает это возможным без экспорта чего-либо, используя ключ API, который владелец учётной записи генерирует и может отозвать.

Related MCP server: lexware-mcp-server

Безопасность прежде всего

Сервер указывает на реальную бухгалтерскую систему, поэтому настройки по умолчанию осторожны.

Запускайте его в режиме только для чтения, если у вас нет причины поступать иначе. Этот сервер может изменять реальные бухгалтерские записи — создавать контакт, записывать ваучер, выставлять счёт, прикреплять квитанцию — и именно ассистент решает, когда вызывать такой инструмент, а не вы. --tools read-only даёт ему всё необходимое для ответов на вопросы о книгах, что и нужно большинству людей: поиск, чтение и скачивание. Ничто в этом наборе не пишет.

Включайте инструмент записи, когда у вас есть для него задача, и знайте, что он оставляет после себя. Этот API вообще не может удалить бухгалтерский ваучер, поэтому ошибка исправляется в веб-приложении, а не отзывается здесь, а окончательный счёт — это реальный документ с использованным номером. Если вы не уверены, какие инструменты вам нужны, режим только для чтения — честная отправная точка: страница разрешений добавит его позже одним кликом, а клиент, поддерживающий notifications/tools/list_changed, как Claude Desktop, подхватит это без перезапуска.

• Ничего не включено, пока вы не скажете об этом. Свежая установка не имеет файла политики, а сервер без него не предлагает никаких инструментов. Что этот сервер может делать — это решение, принятое кем-то, а не случайное значение по умолчанию.

• Один флаг на инструмент, в JSON-файле, который вы пишете с помощью --tools, отмечаете через setup или редактируете вручную. Не уровень, не группа: create_contact включён, а upload_file выключен — обычное желание, и нет комбинации, которую файл не мог бы выразить.

• Стоимость инструмента видна, пока вы решаете. Каждый включённый инструмент отправляется ассистенту при каждом запросе, а страница разрешений помещает это число в каждую строку.

• Файл проверяется дважды: один раз при построении списка инструментов и ещё раз при поступлении вызова, поэтому устаревший список инструментов на клиенте не может проскочить мимо.

• Ключ API никогда не логируется, никогда не возвращается в результате инструмента и удаляется из сообщений об ошибках. Он должен находиться в .env и нигде больше — не в файле конфигурации вашего клиента, которым владеет и перезаписывает другая программа, и который люди скриншотят, когда просят о помощи. Никакой путь с вашей машины не достигает ассистента.

Инструменты

Каждый инструмент ниже реализован и был протестирован на реальной учётной записи. Ни один из них не включён, пока файл политики не назовёт его.

Инструменты чтения:

Инструменты записи. Они изменяют реальные бухгалтерские записи, поэтому включайте их по одному и на учётной записи, которую вы готовы изменить:

update_contact и update_voucher стоят два вызова API вместо одного. API заменяет запись, а не исправляет её, поэтому текущая запись сначала читается, а изменение накладывается поверх. Без этого изменение только адреса электронной почты опустошило бы адреса, примечание и всё остальное. Оба также требуют version, которую вы прочитали последней: если запись изменилась между тем, обновление отклоняется, и ничего не записывается.

Один инструмент удаляет, и он единственный:

Пока это единственный член шага --tools irreversible, поэтому этот шаг — единственный способ его включить. Товар также единственное, что этот API позволяет удалить, что составляет вторую половину смысла:

--tools write — это не то же самое, что отменяемое действие. Ничто из того, что включает этот пресет, не удаляет записи, но два его инструмента создают запись, которую впоследствии нельзя удалить.

Бухгалтерский документ нельзя удалить через API. Для этого нет конечной точки, поэтому ошибочный create_voucher приходится исправлять в веб-приложении Lexware Office, и он проводится в момент создания — API не принимает никакого статуса на входе. То же самое относится к upload_file: загрузка квитанции также создаёт связанный с ней документ, так что она оставляет запись, хотя в названии упоминается только файл.

Загрузки записываются в каталог загрузок на машине, где работает сервер, и сообщаются двумя способами: путь — то, что нужно, когда клиент и сервер находятся на одной машине, и URI ресурса, который клиент может прочитать, чтобы получить байты, где бы ни находился сервер. Сам файл никогда не передаётся внутри результата инструмента, потому что base64 стоит примерно в 1,37 раза больше размера файла в контексте, и ни одна модель всё равно не может прочитать PDF. Существующий файл никогда не заменяется: вторая загрузка сохраняется рядом с первой с счётчиком в имени.

Список ресурсов заполняется из каталога загрузок при запуске сервера, поэтому URI остаётся читаемым после перезапуска. Чего сервер не может сделать, так это объявить о новой загрузке: MCP SDK не даёт ему возможности отправить уведомление об изменении списка, поэтому клиент, который один раз получил список при запуске, не увидит ничего, загруженного позже в течение сеанса.

Между этим и тем, что Claude Desktop вообще не переходит по ссылкам на ресурсы, read_download — это маршрут, который работает всегда. Он принимает тот же URI и помещает содержимое в ответ. Что приходит, зависит от файла:

PDF отображается, а не передаётся напрямую, потому что Claude Desktop превращает встроенный двоичный файл в блок изображения при вызове API, а application/pdf не является разрешённым типом изображения, поэтому весь запрос отклоняется. Рендеринг также не требует вызова API, поскольку файл уже находится на сервере.

Ссылка в веб-приложение — это отдельный инструмент. get_deeplink превращает идентификатор в URL для браузера, не требует вызова API и является маршрутом, который всё ещё работает, когда клиент не может отобразить ни файл, ни ссылку на ресурс: кто-то открывает его сам. Загрузка не несёт такой ссылки — она отвечает, где находятся байты, а это другой вопрос, и однажды их объединили достаточно надолго, чтобы сломанная ссылка поехала вместе с рабочей загрузкой.

upload_file принимает PDF, JPEG, PNG и XML, не более 5 МиБ на файл — именно столько принимает API. XML-файл рассматривается как XRechnung и отклоняется, если он им не является.

Требования

• uv — он приносит собственный Python и команду uvx, которую использует каждый пример ниже

• Python 3.11 или новее, если вы предпочитаете свой. Установка подтягивает MCP SDK, httpx, platformdirs и pypdfium2, последний — для рендеринга страниц PDF

• Учётная запись Lexware Office с включённым дополнением Public API

• Ключ API с https://app.lexware.de/addons/public-api

Получение ключа API

1. Войдите в Lexware Office как владелец учётной записи.

2. Откройте дополнение Public API по адресу https://app.lexware.de/addons/public-api.

3. Создайте ключ и скопируйте его один раз — он показывается только один раз.

4. Не помещайте его ни в один файл, который попадает в систему контроля версий. Поместите его в config/.env, который игнорируется git, или передайте как переменную окружения. Ключ в config/.env находится независимо от того, из какого каталога запускается сервер, поэтому такому клиенту, как Claude Desktop, не нужен собственный ключ в его файле конфигурации.

Ключ можно отозвать на той же странице в любое время — это самый быстрый способ прекратить доступ, если что-то выглядит подозрительно.

Установка

Самый простой способ запустить сервер — без клонирования, без ручного виртуального окружения, без 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 ищет пакет по имени. Две вещи, которые стоит знать об этой записи:

• Закрепите версию для стабильности: "args": ["benethos-lexware-office-mcp==0.2.2"]. Без закрепления uvx берёт самую новую версию, которую может разрешить, и перезапуска клиента достаточно, чтобы изменить то, что он запускает.

• uvx должен быть в PATH, который использует клиент, — это не всегда тот, что в вашем терминале: некоторые GUI-клиенты передают урезанное окружение. Если сервер не запускается, укажите абсолютный путь к uvx в command и полностью перезапустите клиент, а не перезагружайте его.

Предпочитаете собственную команду? uv tool install benethos-lexware-office-mcp даёт вам benethos-lexware-office-mcp без uvx впереди, что стоит того, если вы часто меняете разрешения из командной строки. Больше это ничего не даёт: ту же версию можно закрепить в любом случае, а тёплый старт отличается на десятки миллисекунд. Одна вещь, которую стоит знать: 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 указывает на .venv/Scripts/python.exe в Windows или .venv/bin/python в других системах, с args вида ["-m", "benethos_lexware_office_mcp"].

Ключа там нет намеренно. Сервер находит его в .env. Файл конфигурации клиента — неподходящее место для учётных данных: он не ваш — другая программа владеет им, решает, где он находится и когда его перезаписывает. Это файл, который люди снимают на скриншот, когда просят помощи с настройкой MCP, он читается в собственном представлении настроек клиента и переезжает на следующую машину вместе с остальной конфигурацией клиента. .env — по крайней мере файл, который документирован в этом проекте, который ничего не синхронизирует от вашего имени и который интерфейс конфигурации записывает, никогда не показывая вам ключ обратно.

Этот .env уже та часть, с которой стоит быть осторожным. Он содержит учётные данные для живой бухгалтерской системы, поэтому держите его вне системы контроля версий, вне общих папок и вне резервных копий, которые могут прочитать другие. Когда вы перестанете использовать сервер, удалите его и отзовите ключ в разделе Extensions, Public API — отзыв — единственный шаг, который действительно прекращает доступ.

4. Полностью перезапустите Claude Desktop — выйдите из него через трей, а не закрывайте окно. Это нужно для файла конфигурации, который вы только что отредактировали: клиент читает его один раз при запуске, и это также нужно для изменённой настройки в .env — сервер тоже читает их при запуске. Это не нужно для разрешений: измените их позже, и работающему клиенту будет сообщено, см. Отключение отдельных инструментов.

Настройка в браузере

uvx benethos-lexware-office-mcp setup

Три страницы на 127.0.0.1, закрываются с помощью Ctrl+C. Они записывают те же файлы, что и командная строка, так что вы можете использовать либо то, либо другое, либо оба. Экраны на немецком, потому что Lexware Office продаётся только немецким компаниям, и каждая ниже названа по тому, что она делает, с её ярлыком в скобках.

Обзор (Übersicht) — какие .env и tools.json фактически действуют, во что разрешается каждая настройка и откуда взялось это значение, существует ли каждый файл, сколько инструментов включено и сколько они стоят. Тест соединения по кнопке, никогда при загрузке страницы.

Учётные данные (Zugangsdaten) — ключ API, проверяемый через API перед сохранением, если вы не укажете иное, и настройки, которые не являются секретными. Ключ никогда не показывается вам обратно, никогда не регистрируется и не экспортируется. Если его задаёт переменная окружения, страница сообщает об этом, потому что это переопределит всё, что вы сохраните.

Разрешения (Rechte) — по одному флажку на инструмент, сгруппированные, с пресетами в виде кнопок. При свежей установке, когда файла политики ещё нет, инструменты чтения предварительно отмечены как отправная точка — это предложение в форме, а не разрешение: файла всё ещё нет, и поэтому инструмента тоже нет, пока вы не нажмёте «Сохранить», и страница сообщает об этом. Каждая строка показывает, сколько этот инструмент стоит ассистенту в контексте, и итог следует за вашими отметками: каждый включённый инструмент отправляется модели при каждом запросе, так что включение одного — это решение о бюджете, а также о разрешении. Инструменты записи отмечены, а те, чей результат API не может отозвать, отмечены отдельно: nur App для контакта, который Lexware Office удаляет без церемоний, и nur App · Buchhaltung для записи, которая попадает в книги. Ни то, ни другое не означает, что она застряла — ничего не festgeschrieben при создании, и легенда на странице называет четыре вещи, которые впоследствии связывают запись.

Профили тоже живут здесь. Сохраните текущий выбор под именем, загрузите его позже. Загрузка только заполняет поля: ничего не попадает в tools.json, пока вы не нажмёте «Сохранить». Имя, которое уже занято, отклоняется, а не тихо заменяет существующее — регистр и пробелы не создают второй профиль — и замена имеет свою собственную кнопку рядом со списком. Они хранятся в tool_profiles.json рядом с файлом политики.

Сам файл политики можно скачать и прочитать обратно с той же страницы — файл как есть, так что он работает на другой установке с этим интерфейсом или без него, и tools.json, записанный с помощью --tools, читается здесь. Чтение только отмечает флажки, и сохранение по-прежнему требует отдельного нажатия. Инструмент, который файл не упоминает, остаётся выключенным, и страница сообщает, сколько их, — это то, что делает --tools sync в командной строке.

Две вещи, которые стоит знать. Он привязывается к 127.0.0.1 и ни к чему другому — страницы не имеют пароля, что оправдано только до тех пор, пока они недоступны с другой машины, поэтому нет возможности изменить это. И это отдельная команда: MCP-сервер никогда не обслуживает HTTP, и такой клиент, как Claude Desktop, запускает именно его, а не это.

--port N перемещает его, --no-browser только печатает адрес, а --env-file и --tools-file указывают, какие файлы он редактирует. В отличие от всех остальных мест, эти файлы не обязаны существовать.

Если ваш клиент запускает сервер с --tools-file, передайте setup тот же аргумент — в противном случае он редактирует другой файл и сообщает об успехе. Оба процесса фиксируют свои файлы при запуске и никогда не меняют их впоследствии, и ни один не может видеть, как был запущен другой. Обзор печатает строку "args", которая заставляет вашего клиента соответствовать файлам, которые держит интерфейс, — это более простое направление.

Отключение отдельных инструментов

Один JSON-файл решает, что предлагает этот сервер, и больше ничего. Либо отметьте флажки в setup выше, либо начните файл с

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

который записывает каждый инструмент в tools.json, включая одни и выключая остальные, и печатает, что он сделал. Три пресета, каждый из которых включает последний:

--tools show только сообщает. --tools-file PATH указывает, куда писать, и работает со всеми ними — --tools write --tools-file ./tools.json создаёт файл там.

Пресет перезаписывает весь файл, поэтому ручные правки теряются. Используйте его, чтобы создать файл, а не обновить его. После обновления, приносящего новые инструменты, запустите --tools sync: он записывает их как выключенные, оставляет все ваши флаги нетронутыми и никогда ничего не включает. Именно последнее является причиной того, что это единственный из них, который безопасно запускать из скрипта.

Третий шаг является отдельным, потому что это отдельное решение: то, что удалено, исчезло, поэтому его следует выбирать, называя его, а не выбирая самый большой вариант. Ровно один инструмент несёт такой эффект, delete_article, и это не временное положение дел — статья — единственное, что этот API может удалить, и нет способа забронировать, финализировать или аннулировать что-либо задним числом.

Без --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. .env в каталоге конфигурации для конкретного пользователя

2. config/.env в рабочей копии, с которой запускается сервер, если он запускается из неё

3. config/.env, а затем .env в рабочем каталоге

--env-file называет его вместо этого, и тогда поиск вообще не выполняется. Это то же правило, которому следует --tools-file для файла политики, поэтому оба флага означают одно и то же: этот файл, и ничего больше.

Две вещи находятся вне этого файла, одна ниже и одна выше:

• встроенное значение по умолчанию для настройки, о которой файл не упоминает

• реальная переменная окружения, которая перебивает всё, что говорит файл

Последнее — то, что удивляет людей. Настройка, экспортированная в вашей оболочке, помещённая в блок env клиента или закреплённая в Compose-файле, не может быть изменена редактированием .env — ни вручную, ни через setup. Значение записывается, файл корректен, и ничего не происходит.

Интерфейс конфигурации говорит об этом, а не позволяет вам узнать: каждая настройка несёт значок, называющий её источник, и та, которую удерживает переменная окружения, помечена как таковая. Когда что-то, что вы сохранили, кажется игнорируемым, этот значок — ответ.

В контейнере это не крайний случай. compose.yaml закрепляет транспорт, адрес привязки, порт и разрешённые хосты как реальные переменные окружения, потому что они принадлежат контейнеру, а не установке внутри него. Всё остальное — ключ API, HTTP-токен, лимиты — оставлено тому тому, что делает интерфейс конфигурации способным изменить его.

Тот же порядок применяется к файлу политики, и LXO_MCP_TOOL_POLICY и --tools-file называют его напрямую. Интерфейс закрепляет тот файл, который он нашёл при запуске, поэтому страница не может подменить свой собственный предмет.

Именование файлов

--env-file PATH называет файл настроек вместо поиска и сочетается с --tools-file, так что одна запись в конфигурации клиента несёт свою собственную учётную запись и свои собственные разрешения:

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

Путь, который не существует, отклоняется, а не тихо возвращается к поиску — за исключением setup, который частично существует для создания такого файла.

setup записывает этот файл за вас.

Настройки

Каждая настройка выше используется. LXO_MCP_PAGE_SIZE ограничен 250, что является наименьшим размером страницы, который принимает любая конечная точка, и большее значение отклоняется при запуске, а не превращается в ошибку API позже.

Транспорт

stdio — это значение по умолчанию, и его используют Claude Desktop и аналогичные локальные клиенты: клиент запускает сервер как свой собственный дочерний процесс, и ничто другое не может с ним общаться.

streamable-HTTP и SSE обслуживают те же инструменты на порту, для контейнера или отдельной машины:

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

Две вещи стоят перед этим портом, и ни одна из них не является необязательной. Bearer-токен, который должен нести каждый запрос как Authorization: Bearer <token> — без LXO_MCP_BEARER_TOKEN сервер вообще отказывается запускать HTTP-транспорт, потому что любой, кто может добраться до порта, иначе мог бы потратить ваши учётные данные Lexware. И защита от DNS-ребдинга SDK, которая проверяет Host и Origin по белому списку имён loopback, расширенному с помощью --allowed-hosts, где контейнер или прокси ставит другое имя перед ним.

Ни то, ни другое не делает порт безопасным для публикации в сети. Они делают его выживаемым на машине, разделяемой с другими процессами. --host привязывается где-то кроме loopback, что контейнеру приходится делать — см. В контейнере о том, почему это не то послабление, каким кажется.

В контейнере

Образ публикуется для linux/amd64 и linux/arm64, поэтому для запуска одного из них ничего из этого репозитория не нужно:

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

Закрепите версию для всего, от чего вы зависите — :0.2.2 для точного выпуска, :0.2 для следования его патч-релизам. :latest движется с каждым выпуском, а :edge собирается по требованию из того, что содержит main, и вообще не является выпуском.

С Compose

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 также работает и сохраняет остановленный контейнер для следующего раза.

Как поставляется, compose.yaml собирается из этой рабочей копии. Две закомментированные строки в каждом из двух его сервисов переключают его на опубликованный образ, и тогда этот файл — единственное, что вам нужно отсюда.

Как отдельные контейнеры

docker run -d --name lexware-office-mcp \
  --restart unless-stopped \
  -p 127.0.0.1:8770:8770 \
  -v lxo-config:/config -v lxo-downloads:/downloads \
  ghcr.io/benethos-hub/lexware-office-mcp:latest

Токен, который он сгенерировал для себя, находится в томе конфигурации, откуда вы его читаете:

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

Эта одна строка, а не весь файл: после ввода ключа ключ API тоже находится там, и ему не место прокручиваться в терминале, который вы можете сфотографировать.

Интерфейс конфигурации — это тот же образ с другой его командой, указывающей на тот же том:

docker run --rm -d --name lexware-office-mcp-setup \
  -p 127.0.0.1:8771:8771 \
  -v lxo-config:/config -v lxo-downloads:/downloads \
  ghcr.io/benethos-hub/lexware-office-mcp:latest \
  setup --no-browser --host 0.0.0.0 --port 8771 \
        --env-file /config/.env --tools-file /config/tools.json

Он был запущен с --rm, поэтому его остановка также является его концом:

docker stop lexware-office-mcp-setup

--restart unless-stopped здесь не украшение. Контейнер завершает свой процесс при изменении файла настроек, что переносит сохранённую настройку в работающий сервер. Без политики перезапуска он завершается и остаётся завершённым.

Выключите интерфейс, когда закончите

Откройте http://127.0.0.1:8771/, введите ключ, отметьте инструменты — а затем остановите его. Ничто не остановит его за вас. У него нет входа, он принимает ключ API и будет с радостью продолжать обслуживать эту страницу, пока машина работает.

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 оставляет его выключенным, и у него нет политики перезапуска: после остановки он остаётся остановленным, пока вы снова не запросите его.

Ничего не нужно готовить заранее. При первом запуске сервер создаёт bearer-токен, записывает его в том конфигурации и сообщает об этом — интерфейс показывает его, и это значение, которое нужно клиенту. Он не встроен в образ, где каждая копия делила бы его.

Контейнер привязывается к 0.0.0.0, и это не ослабление. Процесс на собственном loopback контейнера вообще нельзя достичь через опубликованный порт. Изоляция обеспечивается сетевым пространством имён, а кто может получить доступ к порту, решает публикация, которая сопоставляет только 127.0.0.1.

Настройка, сохранённая в браузере, достигает работающего сервера. Настройки читаются один раз при запуске, поэтому контейнеру сообщается о завершении, когда его файл настроек изменяется, и Compose запускает его снова через секунду. То, что Compose закрепляет как реальные переменные окружения — транспорт, адрес привязки, порт, разрешённые хосты — принадлежит контейнеру и не может быть изменено из тома, см. Конфигурация.

Примеры запросов

После подключения сервера такие запросы являются предполагаемым использованием:

• «Какие счета всё ещё открыты, и какие из них просрочены?»

• «Покажи мне всё, что мы выставили клиенту Muster GmbH в этом квартале.»

• «Что содержит счёт RE-2024-0142, и был ли он оплачен?»

• «Найди товар с номером A-1007 и сообщи его текущую цену.»

• «Скачай PDF последнего кредит-ноты, которую мы выпустили.»

• «Дай мне ссылку, чтобы открыть ваучер X в Lexware Office.»

Лимиты запросов

API Lexware допускает два запроса в секунду, что обеспечивается token bucket. Этот бюджет глобальный — он покрывает все конечные точки API одновременно, поэтому чтение контакта и чтение счёта расходуют один и тот же лимит.

Сервер повторяет это с помощью одного token bucket, общего для всех запросов в процессе, по умолчанию пополняясь немного ниже документированной скорости. Lexware отмечает, что точное соблюдение лимита без буфера, как правило, всё равно приводит к 429, как только сетевой джиттер смещает время прибытия, поэтому по умолчанию остаётся запас. Запросы сериализуются через этот bucket, а не запускаются параллельно, что означает, что широкий вопрос, затрагивающий многие документы, становится медленнее, а не блокируется.

Две вещи, которые стоит знать:

• Бюджет принадлежит вашей учётной записи, а не этому процессу. Второй экземпляр сервера, другая интеграция или скрипт, который вы запускаете сами, — все расходуют из тех же двух в секунду.

• Lexware предупреждает, что клиент, который продолжает долбить после 429, может остаться заблокированным навсегда. Поэтому сервер экспоненциально отступает и сдаётся после нескольких попыток, а не повторяет с большим усилием.

Бакет учётной записи был измерен 2026-08-21 и содержит четыре: пять запросов, отправленных одновременно, прошли четыре, а один был отклонён. Значение по умолчанию 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, поэтому работает где угодно. Два вида тестов покидают процесс, не покидая машину: три запускают сервер как реальный подпроцесс и общаются с ним по MCP через stdio, что также доказывает, что ничего не пишется в stdout на пути запуска, а интерфейс конфигурации управляется через реальный loopback HTTP-сервер с реальной cookie jar, потому что его CSRF-защита стоит тестировать только так, как с ней встречается браузер.

Никакой ключ API не поставляется с этим репозиторием, и его нет в CI, поэтому клон никогда не сможет сам общаться с Lexware. Проверка сервера против реального API поэтому всегда является намеренным локальным запуском с ключом, который вы предоставляете, отдельным от вышеуказанного набора и никогда его частью:

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

Он читает вашу учётную запись и ничего в неё не пишет. Сервер, который он создаёт, получает пресет read-only, поэтому инструменты записи вообще недоступны для вызова. Он печатает, что проверил, для чего в учётной записи ничего не было, и что не удалось, и маскирует идентификаторы записей, чтобы отчёт можно было вставить куда-нибудь. pytest никогда его не запускает. См. SPECS.md, раздел 14.1, почему живая проверка не является воротами.

Вклад и проблемы приветствуются. SPECS.md — это место, где записаны проектные решения, с обоснованием и измерениями, стоящими за ними.

Лицензия

MIT. См. LICENSE.

Товарные знаки и принадлежность

Этот проект не связан с Lexware, Haufe-Lexware GmbH & Co. KG или любыми их дочерними компаниями, не одобрен ими и не спонсируется ими. «Lexware» и «Lexware Office» являются товарными знаками их соответствующих владельцев и используются здесь только для обозначения API, с которым интегрируется это программное обеспечение, в описательном смысле.

Программное обеспечение общается исключительно с документированным публичным API, используя учётные данные, которые предоставляет владелец учётной записи и которые он может отозвать. Использование этого API регулируется собственными условиями Lexware, которые вы принимаете независимо от этого проекта.