비공식 Lexware Office MCP 서버

면책 조항

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

• 이 프로젝트는 문서화된 공개 API를 사용하며, 직접 생성하고 직접 폐기할 수 있는 API 키를 사용합니다. 해당 API의 사용은 이 프로젝트와 별개로 귀하가 수락하는 Lexware 자체 약관의 적용을 받습니다. API는 언제든지 변경될 수 있으며, 요청이 속도 제한되거나 차단될 수 있습니다.

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

• 데이터는 불완전하거나 최신이 아닐 수 있습니다. 여기의 어떤 내용도 세무, 회계 또는 법률 자문이 아닙니다. 신고, 감사 또는 장부 기장 의무를 위해 이에 의존하지 마십시오.

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

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

MCP 서버로, MCP 클라이언트(예: Claude Desktop)를 공식 공개 REST API를 통해 Lexware Office 계정에 연결합니다. 인보이스, 연락처, 품목, 전표에 대해 자연어로 질문하고, 클라이언트가 해당 데이터를 가져오게 하십시오.

상태: 0.2.0. 이 서버는 연락처, 전표, 문서를 처리합니다. 찾고, 읽고, 생성하고, 변경하고, 아직 지불되지 않은 금액을 확인하고, 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 키는 절대 기록되지 않으며, 도구 결과로 반환되지 않고, 오류 메시지에서도 삭제됩니다. API 키는 .env 파일에만 있어야 하며 다른 곳에는 없어야 합니다. 다른 프로그램이 소유하고 다시 쓰는 클라이언트의 구성 파일에 두지 마십시오. 그 파일은 사람들이 도움을 요청할 때 스크린샷을 찍는 바로 그 파일입니다. 또한 사용자 컴퓨터의 어떤 경로도 어시스턴트에게 도달하지 않습니다.

도구

구현됨은 지금 작동하는 것을 의미합니다. 나머지는 SPECS.md에 명시되어 있으며 아직 구현되지 않았습니다.

읽기 도구:

쓰기 도구. 이 도구들은 실제 회계 기록을 변경하므로, 변경되어도 괜찮은 계정을 대상으로 한 번에 하나씩 활성화하십시오:

update_contact와 update_voucher는 API 호출을 한 번이 아니라 두 번 사용합니다. API는 레코드를 부분 수정(patch)하지 않고 교체하므로, 현재 값을 먼저 읽은 후 변경 사항을 그 위에 적용합니다. 그렇게 하지 않으면 이메일 주소만 변경하려고 해도 주소, 메모 및 기타 모든 것이 비워집니다. 두 도구 모두 마지막으로 읽은 version이 필요합니다. 그 사이에 레코드가 변경되면 업데이트가 거부되고 아무것도 기록되지 않습니다.

삭제하는 도구가 하나 있으며, 그것이 유일한 삭제 도구입니다:

이는 --tools 단계 중 유일한 구성원이므로, 그 단계만이 이를 켤 수 있는 유일한 방법입니다. 문서는 또한 이 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을 허용하며, 파일당 최대 5MiB입니다. 이것이 API가 받아들이는 한도입니다. XML 파일은 XRechnung으로 처리되며, XRechnung이 아니면 거부됩니다.

요구 사항

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

• Python 3.11 이상 — 직접 설치하려는 경우. 설치 시 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과 같은 클라이언트는 자체 구성 파일에 키를 넣을 필요가 없습니다.

키는 같은 페이지에서 언제든지 폐기할 수 있으며, 이것이 문제가 의심될 때 접근을 차단하는 가장 빠른 방법입니다.

설치

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에 있어야 합니다 — 이는 항상 터미널의 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가 선택하는 기준이며 브라우저 인터페이스가 그룹화하고 표시하는 기준입니다. 호출을 결정하는 일은 절대 하지 않습니다: 오직 파일만이 결정합니다.

구성

값이 어디서 오는지, 그리고 어느 것이 우선하는지

여섯 가지 소스, 낮은 것부터 먼저 — 나중의 것이 앞선 것을 덮어씁니다:

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

그 포트 앞에는 두 가지가 있으며, 둘 다 선택 사항이 아닙니다. 모든 요청이 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

버전을 고정하려면 :latest 대신 :0.2.0을 사용하십시오.

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 키를 받기 때문에, 영구적으로가 아니라 필요한 몇 분 동안만 실행하도록 설계되었습니다.

미리 준비할 것은 없습니다. 첫 시작 시 서버가 베어러 토큰을 생성하고 구성 볼륨에 기록하며 그렇게 알립니다 — 인터페이스가 그것을 표시하고, 그것이 클라이언트가 필요로 하는 값입니다. 모든 복사본이 공유하게 될 이미지에 구워 넣는 것이 아닙니다.

컨테이너가 0.0.0.0에 바인딩하지만 이는 보안 완화가 아닙니다. 컨테이너 자체의 루프백에 있는 프로세스는 게시된 포트를 통해 전혀 도달할 수 없습니다. 격리는 네트워크 네임스페이스가 담당하며, 포트에 도달할 수 있는 대상은 127.0.0.1만 매핑하는 게시(publish) 설정이 결정합니다.

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

예시 프롬프트

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

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

• "이번 분기에 Muster GmbH에 청구한 모든 항목을 보여 줘."

• "청구서 RE-2024-0142에는 어떤 것이 들어 있고, 결제됐나요?"

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

• "우리가 발행한 마지막 credit note의 PDF를 내려받아 줘."

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

요청 속도 제한

Lexware API는 토큰 버킷으로 초당 두 건의 요청을 허용합니다. 이 예산은 전역입니다. 즉, 이는 API의 모든 엔드포인트에 동시에 적용되므로 연락처를 읽는 요청과 청구서를 읽는 요청이 같은 허용량을 사용합니다.

서버는 프로세스 안의 모든 요청이 공유하는 단일 토큰 버킷으로 이를 그대로 반영하며, 기본적으로 문서화된 속도보다 약간 낮게 채워집니다. Lexware는 완충 없이 한도를 정확히 적용하면 네트워크 지터(Jitter) 때문에 도착 시점이 어긋나면서 어차피 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 계층을 목(mock)처리하고 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는 이 검사를 실행하지 않습니다. 라이브 점검이 통과 조건(gate) 방식이 아닌 이유는 SPECS.md 14.1절에 있습니다.

첫 릴리스가 나온 이후부터 기여와 이슈를 환영합니다. 그때까지는 주디자인 결정이 SPECS.md에 기록되고, 실제 API에 대비해 아직 해결해야 할 개방형 질문들도 포함합니다.

라이선스

MIT. LICENSE 참조.

상표 및 제휴

이 프로젝트는 Lexware, Haufe-Lexware GmbH & Co. KG 또는 그 자회사 도진 간 제휴 관계가 없으며, 이들로부터 보증받거나 후원받지 않습니다. "Lexware"와 "Lexware Office"는 해당 각 소유자의 상표이고, 이 소프트웨어가 통합하는 API를 지칭하려는 설명 목적으로만 사용되었습니다.

이 소프트웨어는 계정 소유자가 제공한 취소할 수 있는 자격 증명을 사용해 문서화된 공개 API와만 통신합니다. 해당 API의 사용에는 Lexware 자체 이용 조항이 적용되며, 이는 이 프로젝트와 별개로 귀하가 수락하는 내용입니다.