BuchPilot MCP 서버

DACH(독일, 오스트리아, 스위스) 회계용 MCP 서버 — Claude, Cursor 또는 모든 MCP 호환 클라이언트에서 직접 연락처, 송장, 영수증 및 견적을 관리하세요.

npm version License: MIT

이것은 무엇인가요?

BuchPilot MCP는 귀하의 회계 시스템(현재 Lexoffice)을 AI 어시스턴트와 연결하는 Model Context Protocol 서버입니다. 자연어를 사용하여 Claude Desktop, Cursor 또는 기타 MCP 클라이언트에서 직접 송장을 생성하고, 연락처를 관리하며, 연체된 결제 내역을 확인할 수 있습니다.

주요 기능

15개의 도구를 통한 완전한 회계 자동화
연락처 생성, 조회, 목록 확인, 업데이트
송장 생성, 조회, 목록 확인, 업데이트, PDF 다운로드
영수증 생성, 조회, 목록 확인 (매입 송장, 대변 메모)
견적 생성, 조회
금액 및 연체 일수가 포함된 연체 송장 확인
백엔드 아키텍처 — 현재 Lexoffice 지원, 향후 sevDesk, Billomat 등으로 확장 가능
플러그인 지원 — E-Invoice MCP 도구(einvoice-mcp) 통합 가능
데이터베이스 및 상태 저장 없음 — 순수 API 프록시

설치

사전 요구 사항

Node.js >= 18
API 키가 포함된 Lexoffice 계정

npm (전역 설치)

npm install -g buchpilot-mcp

소스에서 설치

git clone https://github.com/makririch/buchpilot-mcp.git
cd buchpilot-mcp
npm install
npm run build

설정

다음 위치 중 하나에 .buchpilot.json 설정 파일을 생성하세요:

환경 변수 BUCHPILOT_CONFIG에 지정된 경로
~/.buchpilot.json (홈 디렉토리)
./.buchpilot.json (현재 디렉토리)

.buchpilot.json 내용

{
  "backends": {
    "lexoffice": {
      "api_key": "DEIN_LEXOFFICE_API_KEY"
    }
  },
  "default_backend": "lexoffice"
}

Lexoffice API 키 생성

Lexoffice Public API로 이동합니다.
API-Key erstellen(API 키 생성)을 클릭합니다.
키를 복사하여 .buchpilot.json에 붙여넣습니다.

보안 주의: API 키를 Git에 저장하지 마십시오. .buchpilot.json을 .gitignore에 추가하세요.

사용법

서버 시작 (독립 실행형)

# Nach npm install -g:
buchpilot-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev

서버는 stdio를 통해 실행되며 MCP 메시지를 대기합니다.

Claude Desktop에서 사용

자세한 지침은 Claude Desktop 설정 가이드를 참조하세요.

간단 요약 — claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "buchpilot": {
      "command": "npx",
      "args": ["-y", "buchpilot-mcp"],
      "env": {
        "BUCHPILOT_CONFIG": "/Users/DEIN_NAME/.buchpilot.json"
      }
    }
  }
}

예시 (Claude에서 자연어 사용)

서버를 설정한 후 Claude에게 다음과 같이 질문할 수 있습니다:

"Beispiel GmbH 회사를 위한 연락처를 생성해줘. 이메일은 info@beispiel.de야."
"모든 미결제 송장을 보여줘."
"연락처 XYZ에게 송장을 생성해줘: 상담 10시간, 시간당 150 EUR."
"연체된 송장이 무엇인가요?"
"송장 ABC의 PDF를 다운로드해줘."
"월 49 EUR인 라이선스 5개에 대한 견적서를 생성해줘."

도구 참조

매개변수, 입력 예시 및 출력 예시를 포함한 15개 도구의 전체 참조는 docs/tool-reference.md에서 확인할 수 있습니다.

요약 표

도구	설명
`create_contact`	새 연락처 생성 (개인 또는 회사)
`get_contact`	ID로 연락처 조회
`list_contacts`	필터를 사용하여 연락처 목록 확인
`update_contact`	연락처 업데이트
`create_invoice`	항목이 포함된 새 송장 생성
`get_invoice`	ID로 송장 조회
`list_invoices`	송장 목록 확인 (상태별 필터링 가능)
`get_invoice_pdf`	송장을 PDF로 다운로드 (Base64)
`update_invoice`	초안 송장 업데이트
`create_voucher`	새 영수증 생성
`get_voucher`	ID로 영수증 조회
`list_vouchers`	영수증 목록 확인
`create_quotation`	항목이 포함된 새 견적서 생성
`get_quotation`	ID로 견적서 조회
`get_overdue_invoices`	분석을 포함한 연체 송장 확인

E-Invoice 통합

BuchPilot MCP는 선택적으로 E-Invoice MCP 패키지를 통합하여 회계 시스템에서 직접 XRechnung 및 ZUGFeRD를 생성할 수 있습니다:

// In deinem eigenen MCP-Server:
import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);
// Ergebnis: 15 + 4 = 19 Tools

FAQ / 문제 해결

"No .buchpilot.json found"

서버가 설정 파일을 찾지 못했습니다. 홈 디렉토리에 .buchpilot.json을 생성하세요:

echo '{"backends":{"lexoffice":{"api_key":"DEIN_KEY"}},"default_backend":"lexoffice"}' > ~/.buchpilot.json

Lexoffice에서 "401 Unauthorized"

.buchpilot.json의 API 키가 올바른지 확인하세요.
키가 여전히 활성 상태인가요? Lexoffice Public API에서 확인하세요.
API 키는 만료될 수 있으므로 필요시 새로 생성하세요.

"429 Too Many Requests"

Lexoffice는 초당 최대 2개의 요청을 허용합니다. 연속적으로 많은 작업을 수행하는 경우 요청 사이에 잠시 대기하세요.

서버는 시작되었으나 Claude가 도구를 인식하지 못함

claude_desktop_config.json이 올바른지 확인하세요.
설정 변경 후 Claude Desktop을 다시 시작하세요.
로그를 확인하세요: ~/Library/Logs/Claude/mcp.log (macOS).

송장을 업데이트할 수 없음

draft(초안) 상태의 송장만 업데이트할 수 있습니다. 확정된 송장은 변경할 수 없습니다.

백엔드 "sevDesk"를 사용할 수 없음

현재는 Lexoffice 백엔드만 지원됩니다. sevDesk 지원은 예정되어 있습니다. sevDesk의 경우 n8n 노드(n8n-nodes-buchpilot)를 사용할 수 있습니다.

라이선스

MIT — 상업적 용도를 포함하여 자유롭게 사용 가능.

작성자

MaKri — GitHub

buchpilot-mcp