mcp-buchhaltungsbutler

Deutsch | English

BuchhaltungsButler의 API(v1) — 독일의 부기/회계 SaaS — 를 LLM 에이전트를 위한 엄선되고 토큰 효율적인 도구 모음으로 노출하는 MCP(Model Context Protocol) 서버입니다.

비공식 커뮤니티 프로젝트입니다. BuchhaltungsButler와 제휴하지 않으며 BuchhaltungsButler의 보증을 받지 않습니다.

에이전트를 위해 설계되었으며, API를 래핑한 것에 그치지 않습니다

• 48개 엔드포인트를 모두 다루는 30개 도구 — 동일한 작업의 일괄(batch), 목록(list), 단일(singular) 변형이 하나의 도구로 통합되어, 컨텍스트 창이 거의 중복된 도구 정의로 가득 차지 않습니다.

• 기본적으로 간결 — 목록 도구는 별도의 설정 없이 정리되고 LLM 친화적인 필드를 반환합니다. 전체 레코드가 필요할 때는 full: true를 전달하세요.

• 배열 조작 없음 — 인보이스 라인 항목, 전기 분할, 기타 API 특이점이 깔끔한 일반 객체로 노출됩니다. 더 이상 다섯 개의 병렬 배열을 수동으로 동기화할 필요가 없습니다.

• 항상 스펙과 동기화 — 엔드포인트 정의는 BuchhaltungsButler의 공식 API 스펙에서 직접 생성되며, 수동으로 유지 관리되지 않습니다.

Related MCP server: Cuéntica MCP

설정

1. npm install

2. .env.example을 .env에 복사하고 BB_API_CLIENT, BB_API_SECRET, BB_API_KEY를 입력하세요(BuchhaltungsButler → 설정 → API).

3. npm test — 모킹된 HTTP 응답에 대해 실행되며, 실제 자격 증명이 필요 없습니다.

4. npm run build && npm start — 또는 먼저 빌드하지 않고 빠르게 로컬로 실행하려면 npm run dev를 사용하세요.

npm run generate는 src/bb-client/generated/endpoints.ts를 벤더링된 스펙(spec/buchhaltungsbutler-v1.json)에서 재생성합니다. 출력물은 이미 커밋되어 있으므로, 스펙 파일 자체를 업데이트한 후에만 필요합니다.

MCP 클라이언트와 함께 사용하기

.env는 로컬에서 npm run dev/npm start로 실행할 때만 적용됩니다. 실제 MCP 클라이언트(예: Claude Desktop)는 서버를 직접 실행하며 .env를 읽지 않습니다 — 대신 클라이언트 자체의 env 구성을 통해 자격 증명을 전달하세요. claude_desktop_config.json 항목 예시:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-buchhaltungsbutler/dist/index.js"],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

dist/index.js가 존재하도록 먼저 npm run build를 실행하세요.

도구

아키텍처

src/
  config.ts              # env var loading, fail-fast validation
  bb-client/
    generated/            # spec-derived endpoint metadata (regenerate with npm run generate)
    client.ts              # generic HTTP client: auth, api_key injection, error mapping
  formatting/trim.ts       # trims list responses to LLM-friendly fields
  tools/                   # one file per category, curated MCP tools on top of the client
  server.ts, index.ts      # MCP server bootstrap (stdio)
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/

단일 테넌트, 로컬 stdio 전송만 지원 — 원격 호스팅 없음, 멀티 테넌트 지원 없음, OAuth 없음. 자격 증명은 결코 모델에 도달하지 않으며, 클라이언트 계층이 환경 변수에서 자격 증명을 읽어 요청에 주입합니다.

상태

위의 30개 도구가 BuchhaltungsButler의 48개 엔드포인트를 모두 다루며, 모킹된 HTTP 응답에 대해 테스트되었습니다. 아직 실계정으로 검증되지는 않았습니다. 특히 *_id_by_customer 접미사가 붙은 네 개의 엔드포인트(get_receipt, set_receipt_deleted, get_transaction) 또는 원가 장소가 혼재된 배치를 사용하는 add_receipt_postings/add_transaction_postings에서 예상치 못한 오류가 발생하면 이슈를 열어 주세요.

개발

git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test           # vitest run
npm run build       # tsc, strict mode