lexware-mcp-server

Lexware Office API용 MCP 서버입니다. Model Context Protocol을 통해 인보이스, 연락처, 품목, 전표 등을 관리하세요.

비공식 — 커뮤니티 프로젝트입니다. Lexware GmbH 또는 Haufe Group과 제휴, 보증, 지원 관계가 없습니다. "Lexware" 및 "Lexware Office"는 해당 소유자의 상표이며, 이 클라이언트가 대상으로 하는 API를 식별하기 위해서만 사용됩니다(지시적 공정 사용).

20개 리소스 도메인에 걸친 66개 도구와 6개의 진입점을 제공하므로 MCP 클라이언트의 도구 제한에 맞는 서버를 선택할 수 있습니다.

설치

npm install -g @lazyants/lexware-mcp-server

또는 직접 실행:

npx @lazyants/lexware-mcp-server

Related MCP server: e-rechnung-mcp

구성

API 토큰은 다음 순서로 확인됩니다.

1. OS 키링 (권장 — 토큰이 평문으로 디스크에 기록되지 않음)

2. 환경 변수 LEXWARE_API_TOKEN

OS 키링에 토큰 저장

토큰을 Lexware Office API 설정에서 받은 다음 OS의 기본 자격 증명 관리자에 저장하세요.

[!IMPORTANT] 아래 명령은 토큰을 인자로 받지 않고 대화형 프롬프트에서 읽으므로 셸 히스토리나 프로세스 목록에 남지 않습니다. 토큰을 명령줄에 직접 붙여넣지 마세요.

macOS

-w 뒤의 값을 생략하면 security가 토큰을 묻습니다(확인 포함):

security add-generic-password -s "lexware-mcp" -a "api-token" -w

Windows (PowerShell)

cmdkey는 토큰을 명령줄 인자로만 받을 수 있으므로 프로세스 목록에 노출됩니다. 대신 숨겨진 프롬프트에서 토큰을 읽어 CredWrite를 통해 Windows Credential Manager에 직접 기록하므로 토큰이 argv에 전달되지 않습니다. 자격 증명의 대상 이름은 <account>.<service>이며, 기본 서비스의 경우 api-token.lexware-mcp입니다. 서버가 정확히 이 이름을 읽어옵니다:

$secure = Read-Host -AsSecureString "Lexware API token"
Add-Type -Namespace LexwareKeyring -Name Native -MemberDefinition @'
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct CREDENTIAL {
    public uint Flags;
    public uint Type;
    [MarshalAs(UnmanagedType.LPWStr)] public string TargetName;
    [MarshalAs(UnmanagedType.LPWStr)] public string Comment;
    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
    public uint CredentialBlobSize;
    public IntPtr CredentialBlob;
    public uint Persist;
    public uint AttributeCount;
    public IntPtr Attributes;
    [MarshalAs(UnmanagedType.LPWStr)] public string TargetAlias;
    [MarshalAs(UnmanagedType.LPWStr)] public string UserName;
}
[DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern bool CredWriteW(ref CREDENTIAL credential, uint flags);
'@
$blob = [Runtime.InteropServices.Marshal]::SecureStringToCoTaskMemUnicode($secure)
try {
    $cred = New-Object LexwareKeyring.Native+CREDENTIAL
    $cred.Type = 1                              # CRED_TYPE_GENERIC
    $cred.Persist = 2                           # CRED_PERSIST_LOCAL_MACHINE
    $cred.TargetName = 'api-token.lexware-mcp'  # "<account>.<service>"
    $cred.UserName = 'api-token'
    $cred.CredentialBlob = $blob
    $cred.CredentialBlobSize = $secure.Length * 2   # UTF-16 bytes, no terminator
    if (-not [LexwareKeyring.Native]::CredWriteW([ref]$cred, 0)) {
        throw "CredWrite failed (Win32 error $([Runtime.InteropServices.Marshal]::GetLastWin32Error()))"
    }
    Write-Host 'Stored Lexware API token in Windows Credential Manager.'
} finally {
    [Runtime.InteropServices.Marshal]::ZeroFreeCoTaskMemUnicode($blob)
    $secure.Dispose()
    Remove-Variable secure, blob
}

사용자 지정 LEXWARE_KEYRING_SERVICE(예: acme)를 사용 중인가요? TargetName을 api-token.acme로 설정하여 일치시키세요. 서버는 토큰을 <account>.<service> 아래에서 찾습니다.

Linux

secret-tool store --label="Lexware Office API" service lexware-mcp username api-token
# (prompts for the token value)

일단 저장되면 MCP 구성 파일에는 자격 증명이 전혀 필요 없습니다. 서버는 시작 시 키링에서 토큰을 읽습니다.

대신 환경 변수 사용

키링을 사용하지 않으려면 셸 또는 MCP 클라이언트 구성에서 LEXWARE_API_TOKEN을 설정하세요:

export LEXWARE_API_TOKEN=your-token-here

환경 변수

선택적으로 lexware_verify_webhook_signature에서 사용하는 웹훅 서명 공개 키를 재정의할 수 있습니다(기본적으로 Lexware에서 가져와 캐시됨):

export LEXWARE_WEBHOOK_PUBLIC_KEY="$(cat lexware-webhook-public.pem)"

진입점

분할 서버를 사용하면 컨텍스트 크기를 줄일 수 있습니다 — 필요한 분할 항목만 선택하세요.

Claude Code

~/.claude/settings.json에 추가하세요. 토큰을 OS 키링의 기본 서비스 이름 lexware-mcp(권장)로 저장했다면 env 키는 필요 없습니다:

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"]
    }
  }
}

환경 변수 방식을 선호한다면:

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_API_TOKEN": "your-token-here" }
    }
  }
}

분할 서버

분할 서버를 사용하면 컨텍스트 크기를 줄일 수 있습니다 — 필요한 진입점만 선택하세요. -p @lazyants/lexware-mcp-server 플래그는 npx에 명령을 가져올 패키지를 알려줍니다. 마지막 인자(예: lexware-mcp-sales)는 해당 패키지에 정의된 특정 진입점 바이너리입니다(진입점 참조):

{
  "mcpServers": {
    "lexware-sales": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/lexware-mcp-server", "lexware-mcp-sales"]
    },
    "lexware-contacts": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/lexware-mcp-server", "lexware-mcp-contacts"]
    }
  }
}

멀티 계정 예시(두 Lexware 회사, 별도의 키링 서비스 이름으로 저장된 토큰):

{
  "mcpServers": {
    "lexware-company-a": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_KEYRING_SERVICE": "lexware-company-a" }
    },
    "lexware-company-b": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_KEYRING_SERVICE": "lexware-company-b" }
    }
  }
}

Claude Desktop

claude_desktop_config.json에 추가하세요. OS 키링을 사용하는 경우(권장 — 토큰이 기본 서비스 이름 lexware-mcp 아래에 저장되어 있다고 가정):

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"]
    }
  }
}

대신 환경 변수를 사용하는 경우:

{
  "mcpServers": {
    "lexware": {
      "command": "npx",
      "args": ["-y", "@lazyants/lexware-mcp-server"],
      "env": { "LEXWARE_API_TOKEN": "your-token-here" }
    }
  }
}

도구

인보이스 (5개 도구) — sales

lexware_create_invoice (생성 시 finalize=true 지원), lexware_get_invoice, lexware_download_invoice_file, lexware_pursue_invoice, lexware_deeplink_invoice

크레딧 노트 (5개 도구) — sales

lexware_create_credit_note, lexware_get_credit_note, lexware_download_credit_note_file, lexware_pursue_credit_note, lexware_deeplink_credit_note

견적서 (4개 도구) — sales

lexware_create_quotation, lexware_get_quotation, lexware_download_quotation_file, lexware_deeplink_quotation

주문 확인서 (5개 도구) — sales

lexware_create_order_confirmation, lexware_get_order_confirmation, lexware_download_order_confirmation_file, lexware_pursue_order_confirmation, lexware_deeplink_order_confirmation

납품서 (5개 도구) — sales

lexware_create_delivery_note, lexware_get_delivery_note, lexware_download_delivery_note_file, lexware_pursue_delivery_note, lexware_deeplink_delivery_note

선급금 인보이스 (3개 도구) — sales

lexware_get_down_payment_invoice, lexware_download_down_payment_invoice_file, lexware_deeplink_down_payment_invoice

독촉장 (4개 도구) — sales

lexware_get_dunning, lexware_download_dunning_file, lexware_pursue_dunning, lexware_deeplink_dunning

Voucherlist (1개 도구) — sales, bookkeeping

lexware_list_voucherlist

기본적으로 이 도구는 API 응답을 단일 페이지로 그대로 전달합니다. 다음 두 가지 추가 기능은 선택 사항입니다:

• fetchAllPages: true는 모든 페이지를 가져올 때까지 페이지네이션을 따라가며, 최대 100회 요청으로 제한됩니다. 결과에 fetchedPages와 truncated가 추가되며, 후자는 상한으로 인해 잘린 집합을 나타냅니다. totalElements와 같은 API 필드는 유지됩니다.

• contactName(SQL 스타일 %/_ 와일드카드, 대소문자 구분 없음)과 hasOpenAmount는 가져온 후 클라이언트 측에서 필터링하며, 각각 fetchAllPages를 암시합니다. contactName과 openAmount를 제공하는 응답 형태는 /voucherlist이므로 이 필터들은 lexware_list_vouchers가 아닌 여기서 적용됩니다.

page는 세 가지 중 어느 것과도 결합할 수 없습니다. 해당 모드는 모든 페이지를 읽으므로 시작 오프셋은 의미가 없습니다. 대신 size를 사용하여 배치 크기를 제어하세요. 조합은 조용히 무시되지 않고 거부되므로, 오프셋이 실제로 적용되지 않았는데 적용된 것으로 착각할 수 없습니다.

연락처 (5개 도구) — contacts

lexware_list_contacts, lexware_get_contact, lexware_create_contact, lexware_update_contact, lexware_deeplink_contact

품목 (5개 도구) — contacts

lexware_list_articles, lexware_get_article, lexware_create_article, lexware_update_article, lexware_delete_article

전표 (6개 도구) — bookkeeping

lexware_list_vouchers, lexware_get_voucher, lexware_create_voucher, lexware_update_voucher, lexware_upload_voucher_file, lexware_deeplink_voucher

lexware_list_vouchers는 voucherNumber가 필요합니다. GET /vouchers는 조회 엔드포인트이지 탐색 가능한 컬렉션이 아닙니다. 제공하지 않으면 API가 400 "voucherNumber parameter is required"로 응답합니다. 전표를 탐색하거나 필터링하려면 lexware_list_voucherlist를 사용하세요. 이 도구는 컬렉션 엔드포인트이며 /vouchers에는 없는 요약 필드(contactName, openAmount)도 제공합니다.

lexware_get_voucher는 voucherStatus를 소문자로 정규화하고 404를 세 번 재시도합니다(1초 / 2초 / 4초). 업로드 후 인덱싱 지연을 보완하기 위함입니다. 그래도 전표를 찾을 수 없으면 { voucherId, status: "processing", message }를 반환합니다. 그 외의 실패는 오류로 보고됩니다.

지급 (1개 도구) — bookkeeping

lexware_get_payments

국가 (1개 도구) — reference

lexware_list_countries

지급 조건 (1개 도구) — reference

lexware_list_payment_conditions

분개 카테고리 (1개 도구) — reference

lexware_list_posting_categories

프로필 (1개 도구) — reference

lexware_get_profile

인쇄 레이아웃 (1개 도구) — reference

lexware_list_print_layouts

이벤트 구독 (5개 도구) — system

lexware_create_event_subscription, lexware_list_event_subscriptions, lexware_get_event_subscription, lexware_delete_event_subscription, lexware_verify_webhook_signature

파일 (4개 도구) — system

lexware_upload_file, lexware_download_file, lexware_get_file_status, lexware_deeplink_file

lexware_get_file_status는 GET /files/{id}/status를 호출합니다. 단순한 GET /files/{id}는 바이너리 다운로드 경로입니다. Accept: application/json을 사용해도 여전히 200으로 응답하며 파일 본문은 base64로 인코딩되므로 상태 메타데이터를 얻을 수 없습니다. 상태 경로는 범위(scope)로 제한됩니다. 필요한 권한이 없는 API 키는 상태 대신 Lexware에서 access_denied를 받습니다.

두 업로드 도구(lexware_upload_file 및 lexware_upload_voucher_file)는 파일을 contentBase64 또는 filePath로 전달받습니다. filePath는 MCP 서버 프로세스가 읽을 수 있는 절대 경로입니다. 크기가 있는 파일에는 filePath를 권장합니다. base64는 페이로드를 약 1/3 증가시키며, 모델의 컨텍스트 창을 거쳐야 하기 때문입니다. filePath를 사용하면 fileName은 파일의 기본 이름으로 기본 설정되고, contentType은 .png, .jpg/.jpeg, .tiff/.tif, .xml에 대해 자동 감지되며 그 외에는 application/pdf로 대체됩니다. 두 가지 중 정확히 하나만 제공하세요. 둘 다 제공하거나 둘 다 제공하지 않으면 검증 오류입니다.

업로드는 5MB로 제한됩니다. filePath의 경우 파일을 읽기 전에 열린 디스크립터에서 크기를 가져오므로, 크기가 큰 파일은 메모리에 전체를 로드하는 대신 stat 한 번만으로 처리됩니다. 일반 파일이 아닌 것은 아예 거부됩니다(그렇지 않으면 /dev/zero를 읽을 때 영원히 끝나지 않습니다). 이후 디코딩된 바이트 수를 다시 확인하며, 이는 contentBase64에도 적용됩니다. 실패 시 실제 크기와 최대 크기를 포함한 file_too_large 오류가 반환됩니다.

반복 템플릿 (3개 도구) — system

lexware_list_recurring_templates, lexware_get_recurring_template, lexware_deeplink_recurring_template

보안

• OS 키링을 사용하여 API 토큰이 구성 파일과 셸 기록에 전혀 남지 않게 하세요(구성 참조)

• API 토큰을 버전 관리에 커밋하지 마세요

• 리소스를 나열/조회만 하면 되는 경우 읽기 전용 액세스를 사용하세요

• 생성, 업데이트, 삭제 도구는 실제 비즈니스 데이터를 수정합니다 — Lexware 계정의 송장, 연락처, 회계 기록

• 속도 제한은 자동으로 처리됩니다. 429 응답 시 파일 업로드를 포함한 요청이 지수 백오프로 재시도됩니다. multipart 본문은 재시도할 때마다 새로 구성되므로 안전하게 다시 전송할 수 있습니다

릴리스

릴리스는 GitHub 릴리스 이벤트를 통해 배포됩니다. 유지보수자 절차:

1. package.json, package-lock.json, server.json에서 버전을 올리세요(npm version <x.y.z> --no-git-tag-version은 처음 두 파일을 함께 업데이트합니다). npm run check-versions는 package.json#/version, server.json#/packages[0].version, 그리고 package-lock.json의 두 버전 필드(루트와 packages[""])가 모두 일치하지 않으면 하드 실패합니다. server.json#/version은 더 느슨하게 검사됩니다. 해당 필드는 존재해야 하지만 회귀 검사로서 packages[0].version과만 비교됩니다. 레지스트리 전용 재게시는 그 필드만 올리므로 정당하게 앞서 있을 수 있습니다. 따라서 이전 릴리스에 남겨진 값은 WARN: 줄과 함께 실패 없이 통과합니다. 일반적인 릴리스에서는 둘이 함께 움직여야 하므로 종료 코드를 믿지 말고 스크립트 출력을 읽으세요. CHANGELOG.md는 전혀 검사되지 않습니다.

2. CHANGELOG.md를 업데이트하세요.

3. 커밋하고, 릴리스를 만들기 전에 버전 범프를 main에 병합하세요. 그런 다음 직접 확인한 SHA에 태그를 직접 만들고, 그 후에야 그 태그에서 릴리스를 만드세요:

   V=X.Y.Z && PR=<release-pr-number> &&
     SHA="$(gh pr view "$PR" --json mergeCommit -q .mergeCommit.oid)" && test -n "$SHA" &&
     git fetch origin main && git merge-base --is-ancestor "$SHA" origin/main &&
     PKG="$(git show "$SHA:package.json")" &&
     test "$(printf '%s' "$PKG" | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).version')" = "$V" &&
     CL="$(git show "$SHA:CHANGELOG.md")" &&
     printf '%s\n' "$CL" | awk -v v="$V" 'index($0,"## ["v"]")==1{f=1;next} /^## \[/{f=0} /^\[[0-9]+\.[0-9]+\.[0-9]+\]:/{f=0} f' > "/tmp/notes-v$V.md" &&
     grep -q '[^[:space:]]' "/tmp/notes-v$V.md" &&
     git tag -a "v$V" "$SHA" -m "v$V" &&
     git push origin "v$V" &&
     gh release create "v$V" --verify-tag --notes-file "/tmp/notes-v$V.md"

   이 절차가 방지하는 실패: 기존 태그가 없으면 gh release create는 기본 브랜치의 **끝(tip)**에 태그를 생성하므로, 범프가 아직 릴리스 브랜치에 있는 상태에서 실행하면 이전 릴리스의 커밋에 태그가 붙습니다. 그러면 워크플로는 해당 커밋의 package.json에서 찾은 버전을 게시하고, 조용히 이전 버전을 다시 게시하는 vX.Y.Z GitHub 릴리스가 만들어집니다. 5.2.0부터 게시 워크플로 자체가 GITHUB_REF_NAME이 v<package.json version>이 아니면 계속 진행을 거부하므로(#103), 잘못 태그된 릴리스는 이제 조용히 다시 게시하는 대신 npm publish 전에 실패합니다. 다만 그 가드는 워크플로가 이미 실행 중일 때만 작동합니다. 위 절차가 처음부터 잘못된 커밋에 태그가 붙는 것을 막는 것이므로, 워크플로가 실수를 잡아주리라 기대하지 말고 이 절차를 계속 사용하세요.

   각 요소는 모두 중요한 역할을 합니다:

   • **gh pr view … .mergeCommit.oid**는 릴리스 PR 자체의 스쿼시 커밋을 지정합니다. git rev-parse origin/main으로 대체하지 마세요. 그것은 단지 확인하는 시점에 main에 있는 것일 뿐이므로, 그 사이에 들어온 무관한 병합이 대신 태그되어 배포됩니다. gh는 병합되지 않은 PR에 대해 0으로 종료하고 아무것도 출력하지 않으므로 명시적인 test -n이 필요한 것입니다.

   • && 체인은 첫 번째 실패에서 멈추고 되돌릴 수 없는 단계로 넘어가지 않습니다. 두 git show 호출은 직접 파이프로 연결하지 않고 변수에 할당하므로 종료 상태가 실제로 확인됩니다. 파이프라인은 pipefail이 설정되지 않은 한 마지막 명령의 상태만 보고하는데, 여기서는 pipefail을 가정하지 않습니다.

   • **git merge-base --is-ancestor**는 커밋이 실제로 main에서 도달 가능함을 증명합니다. 단순히 존재하는 것만으로는 충분하지 않습니다. 다른 브랜치를 fetch해서 커밋이 로컬에 존재할 수 있고, 버전 파일이 우연히 일치하면 나머지 모든 검사를 통과해 버릴 수 있기 때문입니다.

   • 버전 테스트는 작업 트리가 아니라 대상 커밋에서 package.json을 읽습니다. 작업 트리는 $SHA가 다른 곳을 가리켜도 여전히 올바른 버전을 보여줄 수 있기 때문입니다.

   • **awk**는 해당 버전의 섹션을 커밋의 CHANGELOG.md에서 추출하여 --notes-file에 사용합니다. 이것이 없으면 릴리스 본문은 --notes-from-tag가 주석에서 찾는 내용, 즉 이 흐름에서는 리터럴 문자열 vX.Y.Z가 되는데, 이는 어떤 버전에도 부실한 릴리스 노트이며, 호환성이 깨지는 변경을 포함한 메이저 버전에는 적극적으로 오해를 불러일으키는 내용입니다. 다음 ## [ 제목 또는 첫 번째 링크 참조 정의에서 멈춥니다. 파일에서 가장 오래된 항목 뒤에는 제목이 없어서 그렇지 않으면 링크 참조 블록 전체를 삼켜버리기 때문입니다. 결과는 test -s가 아니라 grep -q로 검사합니다. 빈 줄 외에는 내용이 없는 섹션도 1바이트 파일을 생성하며 test -s는 이를 통과시키기 때문입니다.

   • **--verify-tag**는 푸시가 실제로 반영되지 않았을 때 gh가 태그를 임의로 만들지 않고 중단하게 합니다. 위에서 설명한 gh가 기본 브랜치 끝으로 폴백하는 동작에 대한 방어입니다.

   태그가 이미 푸시된 후 gh release create가 실패하면 전체 블록을 다시 실행하지 마세요. git tag에서 멈출 것이며 그것이 올바른 동작입니다. 마지막 명령만 다시 실행하세요.

4. Publish to npm + MCP Registry 워크플로가 자동으로 실행됩니다. provenance와 함께 npm publish를 실행하고, tarball을 사용할 수 있을 때까지 레지스트리를 폴링한 다음, mcp-publisher를 통해 일치하는 server.json을 MCP Registry에 푸시합니다.

워크플로는 버전이 이미 npm에 있으면 npm publish를 깔끔하게 건너뜁니다(수동으로 일부 게시된 릴리스에 대한 전환 가드).

게시 인증 — npm Trusted Publishing(토큰 없음)

게시는 OIDC를 통한 npm Trusted Publishing을 사용합니다. NPM_TOKEN 시크릿은 없습니다. 워크플로의 id-token: write 권한은 게시 시점에 npm 웹 UI에서 @lazyants/lexware-mcp-server에 대해 구성된 trusted-publisher 바인딩을 사용하여 단기간 유효한 일회용 게시 토큰으로 교환됩니다. 필요한 설정은 npm의 해당 trusted-publisher 바인딩뿐이며, 저장소 시크릿에 아무것도 저장할 필요가 없습니다.

면책 조항

이 프로젝트는 비공식적이고 독립적인 커뮤니티 프로젝트입니다. Lexware GmbH, Haufe Group 또는 그 계열사와 제휴, 보증, 후원, 지원 관계가 아닙니다. 공식 Lexware 지원이 필요하면 Lexware에 직접 문의하세요. 이 MCP 서버의 문제는 Lexware가 아니라 여기에 보고해야 합니다.

"Lexware"와 "Lexware Office"는 해당 소유자의 상표이며, 이 클라이언트가 연결하는 타사 API를 식별하기 위한 목적으로만 이 프로젝트의 이름과 문서에서 지시적 공정 사용(nominative fair use)에 따라 사용됩니다.

생성, 업데이트, 삭제 작업은 Lexware 계정의 실제 비즈니스 데이터를 수정합니다. 저자는 이 소프트웨어를 "있는 그대로(as-is)" 제공하며, 의도하지 않은 변경, 데이터 손실 또는 사용으로 인해 발생하는 기타 어떠한 손해에 대해서도 책임을 지지 않습니다. 프로덕션 데이터에 쓰기 작업을 실행하기 전에 샌드박스 또는 중요하지 않은 계정으로 테스트하세요.

라이선스

FSL-1.1-MIT — 전체 약관은 LICENSE를 참조하세요.