Неофициальный 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.0. Сервер работает с контактами, бухгалтерскими документами и файлами: находит их, читает, создаёт, изменяет, показывает, что ещё не оплачено, скачивает 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 и больше нигде — не в конфигурационном файле вашего клиента, которым владеет и который перезаписывает другая программа, и который люди скриншотят, когда просят о помощи. И никакой путь с вашей машины не достигает ассистента.

Инструменты

Built означает, что это работает уже сегодня. Остальные описаны в SPECS.md и ещё не реализованы.

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

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

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

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

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

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

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

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

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

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

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

Ссылка в веб-приложение — это отдельный инструмент. get_deeplink превращает id в 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, который в gitignore, или передайте как переменную окружения. Ключ в config/.env находится независимо от того, из какого каталога запущен сервер, поэтому такому клиенту, как Claude Desktop, не нужен собственный ключ в его конфигурационном файле.

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

Установка

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.0"]. Без фиксации 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 и по чему браузерный интерфейс группирует и помечает. Она никогда не решает вызов: только файл.

Конфигурация

Откуда берётся значение и какое побеждает

Шесть источников, сначала наименьший — более поздний переопределяет более ранний:

1. встроенное значение по умолчанию

2. .env в каталоге конфигурации пользователя

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

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

5. файл, который называет --env-file, читается после всех них, а не вместо них: он был назван, а не найден, поэтому он превосходит их

6. настоящая переменная окружения, которая побеждает любой файл

Последнее — то, что удивляет людей. Настройка, экспортированная в вашей оболочке, помещённая в блок 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.0 вместо :latest, чтобы закрепить версию.

С Compose

docker compose up -d                      # the server, on 127.0.0.1:8770
docker compose --profile setup up -d      # add the configuration interface

Как поставляется, 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 cat /config/.env

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

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

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

В любом случае

Откройте http://127.0.0.1:8771/, введите ключ, отметьте инструменты, затем снова остановите интерфейс — docker compose --profile setup down, или docker stop lexware-office-mcp-setup. Он предназначен для работы те минуты, когда он нужен, а не постоянно, потому что у него нет входа и он принимает ключ API.

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

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

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

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

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

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

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

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

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

• «Скачай PDF последнего выставленного кредитового авизо».

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

Ограничения частоты запросов

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

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

Две важные вещи:

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

• 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, поэтому запускается где угодно. Два вида тестов завершают процесс, не покидая машину: третий вид запускает сервер как настоящий дочерний процесс и взаимодействует с ним через stdio, что также доказывает, что в процессе запуска ничего не выводится в stdout. Интерфейс конфигурации проверяется через настоящий локальный HTTP-сервер с настоящей cookie-хранилищем, потому что его защиту от 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 — это место, где зафиксированы проектные решения, включая открытые вопросы, которые ещё предстоит решить относительно реального API.

Лицензия

MIT. См. LICENSE.

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

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

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