E-Invoice MCP 서버

DACH 지역(독일, 오스트리아, 스위스) 전자세금계산서를 위한 MCP 서버 — XRechnung 생성, 검증 및 데이터 추출. Claude, Cursor 또는 모든 MCP 클라이언트에서 직접 사용 가능.

npm version License: MIT

이것은 무엇인가요?

E-Invoice MCP는 독일 XRechnung 표준에 따른 전자세금계산서 생성 및 검증을 위한 Model Context Protocol 서버입니다. 2027년부터 독일의 모든 기업은 전자세금계산서를 송신할 수 있어야 합니다. 이 도구로 미리 준비하세요.

Claude에게 간단히 "Beispiel GmbH에 10시간 컨설팅 비용으로 청구서를 작성해줘"라고 말하면, 유효한 UBL 2.1 XML 형식의 XRechnung을 받을 수 있습니다.

주요 기능

XRechnung 생성 — 구조화된 데이터로부터 유효한 UBL 2.1 XML 생성 (EN 16931 + XRechnung 3.0.2)
전자세금계산서 검증 — 구문, 필수 필드 및 독일 비즈니스 규칙(BR-DE) 확인
데이터 추출 — UBL 또는 CII XML에서 구조화된 데이터 읽기
형식 정보 — 필수 필드, 세금 범주, 단위 코드 및 기한에 대한 참조 자료
자동 계산 — 순액, 총액, 세액 자동 계산
플러그인 지원 — 독립 실행형으로 작동하거나 BuchPilot MCP 서버에 통합 가능
외부 서비스 없음 — 모든 작업이 로컬에서 실행되며 API 키가 필요 없음
네이티브 의존성 없음 — Node.js가 설치된 모든 시스템에서 실행 가능

법적 기한

날짜	내용
2025.01.01	모든 기업은 전자세금계산서를 수신할 수 있어야 함
2026.12.31	수신자의 동의가 있는 경우에만 PDF 송장 허용
2027.01.01	매출 80만 유로 초과 기업은 전자세금계산서를 송신해야 함
2028.01.01	모든 기업은 전자세금계산서를 송신해야 함

잘못된 전자세금계산서는 매입세액 공제 불가 및 6% 이자 가산의 원인이 될 수 있습니다.

설치

요구 사항

Node.js >= 18

npm (전역)

npm install -g einvoice-mcp

소스에서 설치

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

설정

이 MCP 서버는 별도의 설정이 필요하지 않습니다. API 키나 외부 서비스가 필요 없으며, 모든 것이 로컬에서 실행됩니다.

사용법

서버 시작 (독립 실행형)

# Nach npm install -g:
einvoice-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev

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

Claude Desktop에서 사용

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

요약하자면, claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "einvoice": {
      "command": "npx",
      "args": ["-y", "einvoice-mcp"]
    }
  }
}

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

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

"Beispiel GmbH에 150유로로 10시간 컨설팅에 대한 XRechnung을 생성해줘"
"이 XML 파일이 유효한 XRechnung인가요?"
"이 XML에서 송장 데이터를 추출해줘"
"XRechnung에 필요한 필수 필드는 무엇인가요?"
"세금 범주에는 어떤 것이 있고 각각 무엇을 의미하나요?"
"우리 회사는 언제까지 전자세금계산서를 송신할 수 있어야 하나요?"

퀵스타트

"5분 만에 첫 XRechnung 만들기" 단계별 가이드는 docs/quickstart.md에서 확인할 수 있습니다.

도구 참조

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

요약

도구	설명
`create_xrechnung`	구조화된 데이터로 XRechnung (UBL 2.1 XML) 생성
`validate_invoice`	전자세금계산서 XML 검증 (구문 + BR-DE 비즈니스 규칙)
`extract_data`	UBL 또는 CII XML에서 구조화된 데이터 추출
`get_format_info`	형식, 필수 필드, 코드 및 기한에 대한 참조 자료

BuchPilot 통합

E-Invoice MCP는 BuchPilot MCP 서버의 플러그인으로 통합될 수 있습니다:

import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);

조합: BuchPilot이 Lexoffice에서 송장을 생성 -> 데이터 추출 -> XRechnung 생성 -> 완성된 전자세금계산서.

지원 표준

표준	버전	상태
XRechnung	3.0.2	생성 + 검증
EN 16931	—	XRechnung의 기반
UBL 2.1	—	XRechnung용 XML 구문
CII (Cross Industry Invoice)	—	추출 (읽기)
ZUGFeRD / Factur-X	2.3	추출 (읽기), 생성 예정

FAQ / 문제 해결

"XML을 파싱할 수 없습니다"

XML이 잘 구성되어 있나요? (모든 태그가 올바르게 닫혔나요?)
실제로 UBL 또는 CII 송장인가요? (루트 요소가 <Invoice> 또는 <CrossIndustryInvoice>여야 합니다)
인코딩이 UTF-8인가요?

검증 시 "BR-DE-13: Buyer Reference는 필수입니다" 오류 발생

구매자 참조(BT-10)는 XRechnung에서 필수입니다. 공공 기관에 대한 송장의 경우 이는 Leitweg-ID입니다. B2B 송장의 경우 임의의 참조(예: 주문 번호)가 될 수 있습니다.

{
  "buyerReference": "04011000-12345-67"
}

검증 시 "BR-DE-21: 전화번호 권장" 경고 발생

이는 경고일 뿐 오류가 아닙니다. 송장은 여전히 유효합니다. 최상의 호환성을 위해 판매자의 전화번호를 기재하는 것이 좋습니다.

세금 범주에는 어떤 것이 있나요?

코드	이름	설명	세율
S	표준	일반 세율	19%, 7%
Z	영세율	0% (예: 부가세 면제 대상 역내 거래)	0%
E	면세	예: 독일 부가세법 제19조에 따른 소규모 사업자	0%
AE	역과세	수취인 납세 의무 (부가세법 제13b조)	0%
K	역내 거래	면세 역내 공급	0%

단위 코드에는 어떤 것이 있나요?

코드	이름	설명
H87	개	개별 단위 (기본값)
HUR	시간	작업 시간
DAY	일	작업일
MON	월	달력 월
KGM	킬로그램	무게
MTR	미터	길이
LTR	리터	부피
MTK	제곱미터	면적
SET	세트/패키지	구성품
C62	단위 (일반)	일반 수량 단위

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

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

라이선스

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

작성자

MaKri — GitHub

einvoice-mcp