비공식 Lexware Office MCP 서버

고지 사항

• 이 프로젝트는 Lexware 또는 Haufe-Lexware GmbH & Co. KG와 제휴, 보증 또는 후원 관계가 아닙니다. "Lexware" 및 "Lexware Office"는 해당 소유자의 상표입니다.

• 이 프로젝트는 문서화된 공개 API를 사용하며, 직접 생성하고 취소할 수 있는 API 키를 사용합니다. 해당 API의 사용은 Lexware의 자체 약관에 따르며, 이는 이 프로젝트와 별개로 수락하는 것입니다. API는 언제든지 변경될 수 있으며, 요청은 속도 제한 또는 차단될 수 있습니다.

• 이 프로젝트는 실제 회계 기록에 접근합니다. 쓰기 액세스는 기본적으로 꺼져 있습니다. 활성화하면 API를 통해 생성된 모든 것은 실제이고 법적으로 관련된 기록입니다. 확정된 문서는 API를 통해 철회할 수 없습니다.

• 데이터는 불완전하거나 오래되었을 수 있습니다. 여기의 어떤 것도 세금, 회계 또는 법률 자문이 아닙니다. 신고, 감사 또는 장부 의무에 의존하지 마십시오.

• 보증 없이 "있는 그대로" 제공됩니다. 개인 및 전문적인 용도로 사용자의 책임 하에 사용하도록 고안되었습니다. LICENSE를 참조하십시오.

• 상업적 사용의 경우 Lexware의 API 약관과 자체 보존 및 문서화 의무를 검토하십시오.

MCP 서버로, Claude Desktop과 같은 MCP 클라이언트를 공식 공개 REST API를 통해 Lexware Office 계정에 연결합니다. 인보이스, 연락처, 품목 및 바우처에 대해 자연어로 질문하고 클라이언트가 이를 가져오도록 할 수 있습니다.

상태: 0.2.2. 서버는 연락처, 바우처 및 문서를 처리합니다: 찾기, 읽기, 생성, 변경, 미지급 항목 확인, PDF 다운로드 및 영수증 업로드. get_profile은 연결된 계정을 알려줍니다. 아래 표의 모든 도구는 구축되었으며 각각 실제 계정으로 테스트되었습니다. 서버는 시작한 클라이언트와 stdio로 통신하고, 다른 곳에서 접근해야 하는 경우 베어러 토큰 뒤의 streamable HTTP로 통신합니다. 게시된 컨테이너 이미지와 두 가지를 위한 Compose 파일이 포함됩니다. 전체 기술 사양 및 로드맵은 SPECS.md를 참조하십시오.

왜 존재하는가

Lexware Office는 소규모 비즈니스의 일상적인 회계를 보유합니다. 이에 대한 대부분의 질문은 읽기 질문입니다 — 아직 지불되지 않은 것, 이 고객이 주문한 것, 해당 비용에 속하는 영수증 — 그리고 이는 어시스턴트가 데이터를 볼 수 있게 되면 잘 대답하는 질문입니다. 이 서버는 계정 소유자가 생성하고 취소할 수 있는 API 키를 사용하여 내보내기 없이 이를 가능하게 합니다.

Related MCP server: lexware-mcp-server

안전 우선

서버는 실제 회계 시스템을 대상으로 하므로 기본값은 신중합니다.

이유가 없는 한 읽기 전용으로 실행하십시오. 이 서버는 실제 회계 기록을 변경할 수 있습니다 — 연락처 생성, 바우처 기록, 인보이스 발행, 영수증 첨부 — 그리고 그러한 도구를 호출할지 결정하는 것은 사용자가 아니라 어시스턴트입니다. --tools read-only는 장부에 대한 질문에 답하는 데 필요한 모든 것을 제공하며, 이는 대부분의 사람들이 원하는 것입니다: 검색, 읽기 및 다운로드. 이 세트에는 쓰기가 없습니다.

작업이 있을 때 쓰기 도구를 켜고, 그 도구가 남기는 것을 알고 있어야 합니다. 이 API는 장부 바우처를 삭제할 수 없으므로 잘못된 것은 여기서 철회하는 대신 웹 앱에서 수정되며, 확정된 인보이스는 번호가 사용된 실제 문서입니다. 필요한 도구가 확실하지 않다면 읽기 전용이 정직한 시작점입니다 — 권한 페이지에서 나중에 한 번의 클릭으로 추가할 수 있으며, Claude Desktop과 같이 notifications/tools/list_changed를 존중하는 클라이언트는 재시작 없이 이를 인식합니다.

• 사용자가 말할 때까지 아무것도 활성화되지 않습니다. 새 설치에는 정책 파일이 없으며, 정책 파일이 없는 서버는 도구를 전혀 제공하지 않습니다. 이 서버가 할 수 있는 일은 누군가가 내린 결정이지, 기본값이 아닙니다.

• 도구당 하나의 플래그, --tools로 작성하는 JSON 파일에 있습니다. 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도 마찬가지입니다. 영수증을 업로드하면 그에 딸린 전표도 함께 생성되므로, 이름이 파일만 언급하더라도 레코드가 남게 됩니다.

다운로드는 서버가 실행되는 머신의 다운로드 디렉터리에 기록되며 두 가지 방식으로 보고됩니다. **경로(path)**는 클라이언트와 서버가 같은 머신을 공유할 때 원하는 방식이고, **리소스 URI(resource 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을 허용하며 파일당 최대 5MiB로, API가 받아들이는 한도입니다. XML 파일은 XRechnung으로 취급되며 XRechnung이 아니면 거부됩니다.

요구 사항

• uv — 자체 Python과 아래 모든 예시에서 사용하는 uvx 명령을 포함합니다

• Python 3.11 이상 — 자체 Python을 사용하려는 경우. 설치 시 MCP SDK, httpx, platformdirs 및 pypdfium2가 함께 설치되며, 마지막 것은 PDF 페이지 렌더링용입니다

• 공개 API 애드온이 활성화된 Lexware Office 계정

• https://app.lexware.de/addons/public-api에서 발급한 API 키

API 키 발급

1. 계정 소유자로 Lexware Office에 로그인합니다.

2. https://app.lexware.de/addons/public-api에서 공개 API 애드온을 엽니다.

3. 키를 생성하고 한 번 복사합니다 — 한 번만 표시됩니다.

4. 버전 관리에 들어가는 파일에 키를 넣지 마세요. config/.env에 넣으면 gitignore되어 있으며, 또는 환경 변수로 전달할 수 있습니다. 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에 있어야 합니다. 이는 항상 터미널의 PATH와 같지 않습니다 — 일부 GUI 클라이언트는 축소된 환경을 전달합니다. 서버가 시작되지 않으면 command에 uvx의 절대 경로를 넣고, 클라이언트를 다시 로드하는 대신 완전히 재시작하세요.

자체 명령을 원하시나요? uv tool install benethos-lexware-office-mcp를 실행하면 uvx 접두사 없이 benethos-lexware-office-mcp를 얻을 수 있습니다. 명령줄에서 권한을 자주 변경한다면 유용합니다. 그 외에는 이득이 없습니다. 같은 버전을 어느 쪽이든 고정할 수 있고, 웜 스타트 차이는 수십 밀리초에 불과합니다. 한 가지 알아둘 점 — 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

그러면 클라이언트는 해당 체크아웃의 가상 환경 인터프리터가 필요하며, Windows에서는 command가 .venv/Scripts/python.exe를, 그 외에서는 .venv/bin/python을 가리키고 args는 ["-m", "benethos_lexware_office_mcp"]입니다.

의도적으로 키가 없습니다. 서버는 .env에서 키를 찾습니다. 클라이언트의 구성 파일은 자격 증명을 넣을 잘못된 곳입니다. 그 파일은 당신의 것이 아닙니다 — 다른 프로그램이 소유하고, 위치와 재작성 시점을 결정합니다. MCP 설정에 대해 도움을 요청할 때 사람들이 스크린샷을 찍는 파일이고, 클라이언트 자체 설정 화면에서 읽을 수 있으며, 클라이언트 구성의 나머지와 함께 다음 머신으로 이동합니다. .env는 적어도 이 프로젝트가 문서화하고, 아무것도 사용자를 대신해 동기화하지 않으며, 구성 인터페이스가 키를 다시 표시하지 않고 쓰는 파일입니다.

그 .env가 이미 주의해야 할 부분입니다. 실제 회계 시스템의 자격 증명을 보관하므로 버전 관리, 공유 폴더, 다른 사람이 읽을 수 있는 백업에서 제외하세요. 서버 사용을 중단하면 삭제하고 확장 프로그램, 공개 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로 작성된 tools.json도 여기서 읽힙니다. 읽어들이면 상자만 체크되고 저장은 여전히 별도의 누름입니다. 파일이 언급하지 않는 도구는 꺼진 상태로 유지되며 페이지에 그 수가 표시됩니다. 이것이 명령줄에서 --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

그 포트 앞에는 두 가지가 있으며, 둘 다 선택 사항이 아닙니다. 모든 요청이 Authorization: Bearer <token>으로携带해야 하는 베어러 토큰 — LXO_MCP_BEARER_TOKEN이 없으면 서버는 HTTP 전송 시작을 거부합니다. 포트에 도달할 수 있는 사람이면 누구든 Lexware 자격 증명을 사용할 수 있기 때문입니다. 그리고 SDK의 DNS 리바인딩 가드는 루프백 이름의 허용 목록에 대해 Host와 Origin을 확인하며, 컨테이너나 프록시가 다른 이름을 앞에 두는 경우 --allowed-hosts로 확장됩니다.

둘 중 어느 것도 포트를 네트워크에 공개해도 안전하게 만들지 않습니다. 다른 프로세스와 공유되는 머신에서 생존 가능하게 만들 뿐입니다. --host는 루프백이 아닌 다른 곳에 바인드하며, 컨테이너는 그렇게 해야 합니다 — 이것이 보이는 것처럼 완화가 아닌 이유는 컨테이너에서를 참조하세요.

컨테이너에서

이미지는 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에 바인딩되며, 이는 완화 조치가 아닙니다. 컨테이너 자체 루프백의 프로세스는 게시된 포트를 통해 전혀 도달할 수 없습니다. 격리는 네트워크 네임스페이스이며, 포트에 도달할 수 있는 주체는 127.0.0.1만 매핑하는 게시(publish) 설정이 결정합니다.

브라우저에 저장된 설정은 실행 중인 서버에 도달합니다. 설정은 시작 시 한 번만 읽히므로, 설정 파일이 변경되면 컨테이너가 종료되도록 지시되고 Compose가 1초 후 다시 시작합니다. Compose가 실제 환경 변수로 고정하는 것(전송 방식, 바인딩 주소, 포트, 허용 호스트)은 컨테이너에 속하므로 볼륨에서 변경할 수 없습니다. 구성을 참조하세요.

예시 프롬프트

서버가 연결되면 다음과 같은 프롬프트가 의도된 사용 방식입니다:

• "아직 열려 있는 청구서는 무엇이고, 그중 연체된 것은 무엇인가요?"

• "이번 분기에 Muster GmbH 고객에게 청구한 모든 내역을 보여줘."

• "청구서 RE-2024-0142에 무엇이 포함되어 있고, 지불되었나요?"

• "품번 A-1007을 찾아 현재 가격을 알려줘."

• "우리가 발행한 마지막 대변 메모의 PDF를 다운로드해줘."

• "Lexware Office에서 바우처 X를 열 수 있는 링크를 줘."

속도 제한

Lexware API는 초당 두 개의 요청을 허용하며, 토큰 버킷으로 강제됩니다. 이 예산은 전역적입니다. API의 모든 엔드포인트를 동시에 포괄하므로, 연락처를 읽는 것과 청구서를 읽는 것이 동일한 허용량을 사용합니다.

서버는 프로세스의 모든 요청이 공유하는 단일 토큰 버킷으로 이를 반영하며, 기본적으로 문서화된 속도보다 약간 낮게 재충전됩니다. Lexware는 버퍼 없이 제한을 정확히 적용하면 네트워크 지터가 도착 시간을 흔들 때 어차피 429가 발생하는 경향이 있다고 언급하므로, 기본값은 여유를 둡니다. 요청은 병렬로 발사되지 않고 해당 버킷을 통해 직렬화되므로, 많은 문서를 다루는 광범위한 질문은 차단되는 대신 더 느려집니다.

알아둘 만한 두 가지 사항:

• 예산은 이 프로세스가 아닌 계정에 속합니다. 서버의 두 번째 인스턴스, 다른 통합, 또는 직접 실행하는 스크립트 모두 동일한 초당 두 개를 사용합니다.

• Lexware는 429 이후에도 계속 요청을 보내는 클라이언트는 영구적으로 차단될 수 있다고 경고합니다. 따라서 서버는 지수적으로 백오프하고 더 강하게 재시도하는 대신 몇 번의 시도 후 포기합니다.

계정의 버킷은 2026-08-21에 측정되었으며 4개를 보유합니다. 한 번에 다섯 개의 요청을 보냈을 때 네 개가 통과하고 하나가 거부되었습니다. 기본값인 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를 통해 MCP로 통신하는데, 이는 시작 경로에서 stdout에 아무것도 쓰지 않는다는 것을 증명하기도 합니다. 구성 인터페이스는 실제 루프백 HTTP 서버와 실제 쿠키 저장소로 구동되는데, CSRF 가드는 브라우저가 마주치는 방식으로만 테스트할 가치가 있기 때문입니다.

이 저장소에는 API 키가 포함되어 있지 않으며 CI에도 없으므로, 체크아웃만으로는 Lexware에 직접 통신할 수 없습니다. 따라서 실제 API에 대한 서버 검증은 항상 사용자가 제공한 키로 의도적으로 로컬에서 실행하는 것이며, 위 스위트와 분리되어 있고 절대 그 일부가 아닙니다:

uv run python tests/smoke.py
uv run python tests/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 자체 약관의 적용을 받으며, 이는 이 프로젝트와 별개로 수락하는 것입니다.