mcp-einvoicing-de 🇩🇪

Name: mcp-einvoicing-de
Author: cmendezs

License PyPI version Python mcp-einvoicing-de MCP server

독일 전자 세금 계산서(ZUGFeRD 2.x 및 XRechnung 3.x 형식, EN 16931, FeRD, KoSIT 준수)를 위한 Python 기반 MCP(Model Context Protocol) 서버입니다. AI 에이전트(Claude, IDE 등)가 독일 B2B 전자 세금 계산서 의무화(2025년 시행, 2027~2028년까지 단계적 적용) 및 유럽 표준 EN 16931을 완벽하게 준수하는 전자 세금 계산서를 생성, 검증, 파싱 및 변환할 수 있도록 지원합니다.

영어 요약

이 서버는 독일 전자 세금 계산서를 위한 MCP(Model Context Protocol) 서버입니다. ZUGFeRD 또는 XRechnung 계산서의 전체 수명 주기를 다루는 6가지 도구를 제공합니다: 생성(CII/UBL XML), EN 16931 및 KoSIT Schematron 규칙(BR-DE-*)에 따른 검증, 기존 계산서 파일 파싱, 프로필 및 구문 변환, Peppol 참가자 등록 조회(AS4), 독일 부가가치세 규칙(세율 등급, §13b UStG 역과세, 면세) 확인. 모든 ZUGFeRD 2.x 프로필(MINIMUM ~ EXTENDED) 및 XRechnung 3.x(CII 및 UBL 구문)를 지원합니다. Apache 2.0 라이선스로 제공됩니다.

기반 기술

이 패키지는 유럽 전자 세금 계산서 MCP 서버를 위한 공통 기반 라이브러리인 mcp-einvoicing-core를 기반으로 합니다. 이 라이브러리는 공통 모델, 검증 추상화, XML 도우미 함수 및 예외 계층 구조를 제공합니다.

mcp-einvoicing-core는 전이적 의존성으로 자동 설치되므로 별도의 추가 단계가 필요하지 않습니다.

개발자 참고: pip install -e ".[dev]" 명령어를 사용하면 PyPI에서 기본 패키지가 자동으로 설치됩니다.

🏗️ 아키텍처

mcp-einvoicing-de (dieses Paket — eigenständiger MCP-Server)
├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic-Modelle (alle Profile)
├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* Regeln
├── KoSITValidator                     ← Remote-Validierungstool (optional)
└── Tools: create / validate / parse / convert / peppol_check / tax_rules

        ↑ erweitert
mcp-einvoicing-core (gemeinsame Basis, als Abhängigkeit installiert)
├── BaseDocumentGenerator / Validator / Parser
├── BaseInvoice, BaseParty … (Pydantic)
├── xml_utils, exceptions
└── EInvoicingMCPServer

🚀 설치

PyPI를 통한 설치 (권장)

pip install mcp-einvoicing-de

uvx를 사용하여 사전 설치 없이 실행:

uvx mcp-einvoicing-de

소스 코드에서 설치

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

⚙️ 설정

v0.1.0 버전에서는 외부 자격 증명이 필요하지 않습니다. 사용 가능한 환경 변수는 다음과 같습니다:

변수	설명	기본값
`EINVOICING_DE_LOG_LEVEL`	로그 수준 (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`
`EINVOICING_DE_KOSIT_VALIDATOR_URL`	KoSIT 검증 도구 URL (선택 사항, 원격 검증용)	—
`EINVOICING_DE_PEPPOL_SMP_URL`	Peppol-SMP 조회 URL (선택 사항)	—
`EINVOICING_DE_PDF_ENGINE`	PDF 생성 엔진 (`reportlab` 또는 `pymupdf`)	`reportlab`

🤖 Claude Desktop 통합

claude_desktop_config.json 파일에 추가:

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

⌨️ Cursor 통합

설정 파일 (~/.cursor/mcp.json 또는 프로젝트 디렉토리의 .cursor/mcp.json):

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

🪐 Kiro 통합

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

🧰 사용 가능한 MCP 도구

도구	설명
`invoice_create`	ZUGFeRD 또는 XRechnung XML(CII 또는 UBL) 생성; PDF/A-3 하이브리드 지원 예정 (v0.2.0)
`invoice_validate`	EN 16931 및 KoSIT Schematron 규칙(BR-DE-*)에 따라 계산서 검증
`invoice_parse`	기존 ZUGFeRD 또는 XRechnung 파일에서 구조화된 데이터 추출
`invoice_convert`	ZUGFeRD 프로필 간 또는 ZUGFeRD ↔ XRechnung 간 변환
`peppol_check`	독일 기업의 Peppol 참가자 등록 확인 (AS4)
`tax_rules`	독일 부가가치세 규칙 조회 (세율 등급, §13b UStG, 면세)

사용 예시

예시 1 — 계산서 검증

1. invoice_validate(
     xml_base64="...",   # Base64-kodiertes ZUGFeRD-XML
     strict=True
   )
   → {
       "is_valid": true,
       "profile": "EN_16931",
       "syntax": "CII",
       "error_count": 0,
       "warning_count": 2,
       "errors": [],
       "warnings": [...],
       "validator_used": "local_schematron"
     }

예시 2 — 독일 세금 규칙 조회

2. tax_rules(query="reverse_charge", context="Bauleistungen")
   → {
       "results": [
         {
           "paragraph": "§13b Abs. 2 Nr. 5 UStG",
           "description_en": "Construction services (building contractor rule)",
           "vatex_code": "VATEX-EU-AE",
           "invoice_note": "Steuerschuldnerschaft des Leistungsempfängers (§13b UStG)"
         }
       ],
       "legal_disclaimer": "..."
     }

예시 3 — Peppol 등록 확인

3. peppol_check(
     participant_id="0204:991-1234512345-06",
     environment="production"
   )
   → {
       "is_registered": true,
       "participant_id": "0204:991-1234512345-06",
       "document_type_supported": true,
       "access_point_url": "https://ap.example.de/as4",
       "transport_profile": "peppol-transport-as4-v2.0"
     }

예시 4 — 계산서 데이터 파싱

4. invoice_parse(xml_base64="...", include_raw_xml=False)
   → {
       "profile": "XRECHNUNG",
       "syntax": "CII",
       "invoice_number": "RE-2025-001",
       "invoice_date": "2025-01-15",
       "seller_name": "Muster GmbH",
       "buyer_name": "Käufer AG",
       "tax_inclusive_amount": "119.00",
       "currency_code": "EUR"
     }

📚 지원 표준

표준	버전	프로필 / 구문
ZUGFeRD	2.3	MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED
XRechnung	3.x	CII (Cross Industry Invoice), UBL (Universal Business Language)
EN 16931	—	전자 세금 계산서를 위한 유럽 핵심 데이터 모델
Peppol BIS	3.0	Billing 3.0 (DE PINT)

참고: ZUGFeRD 2.x와 XRechnung 3.x는 EN 16931 프로필 수준에서 동일한 CII-XML 구문을 공유합니다. 따라서 데이터 손실 없이 두 형식 간 변환이 가능합니다. EXTENDED 프로필은 ZUGFeRD 전용이며 XRechnung 대응 항목이 없습니다.

리소스	링크
FeRD ZUGFeRD 사양	ferd-net.de
KoSIT XRechnung	xeinkauf.de
KoSIT 검증 도구	github.com/itplr-kosit/validationtool
EN 16931-1:2017	CEN
Peppol BIS Billing 3.0	docs.peppol.eu

🧪 테스트

# Entwicklungsabhängigkeiten installieren
pip install -e ".[dev]"

# Gesamte Testsuite ausführen
pytest tests/ -v

# Mit Abdeckungsbericht
pytest --cov=mcp_einvoicing_de --cov-report=term-missing

# Nur Modell-Tests
pytest tests/test_models.py -v

로드맵

버전	기능
v0.1.0 (현재)	도구: create, validate, parse, convert, peppol_check, tax_rules
v0.2.0	`reportlab` / `PyMuPDF`를 통한 PDF/A-3 임베딩 (ZUGFeRD 하이브리드)
v0.3.0	KoSIT 온라인 검증기 통합 완료
v0.4.0	Peppol AS4 직접 전송
v0.5.0	DATEV 내보내기 형식
v1.0.0	프로덕션 준비 완료, EN 16931 전체 지원

기여하기

기여를 환영합니다. 중요한 변경 사항에 대한 Pull Request를 제출하기 전에 먼저 이슈를 열어주시기 바랍니다.

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de
pip install -e ".[dev]"
pytest
make audit

기타 전자 세금 계산서 MCP 서버

국가	서버
🌍 글로벌	mcp-einvoicing-core
🇧🇪 벨기에	mcp-einvoicing-be
🇫🇷 프랑스	mcp-facture-electronique-fr
🇮🇹 이탈리아	mcp-fattura-elettronica-it
🇩🇪 독일	mcp-einvoicing-de

📄 라이선스

이 프로젝트는 Apache-2.0 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

프로젝트 관리자: cmendezs. ZUGFeRD 또는 XRechnung 사양 구현과 관련된 질문은 이슈를 열어주시기 바랍니다.

mcp-einvoicing-de