BeeL MCP server

AI 에이전트가 법적으로 적합한 스페인 전자 송장을 발행할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. AEAT에 VeriFactu 등록, F1/F2 송장 유형, R1–R5 수정, 인구 조사에 대한 NIF 검증, 그리고 규정이 요구하는 제도 키를 지원합니다. Claude, ChatGPT, Cursor 또는 VS Code에 연결하면 에이전트가 스페인 송장 처리 — facturación electrónica 및 factura electrónica VeriFactu — 를 API 호출을 직접 작성하지 않고도 처음부터 끝까지 처리할 수 있습니다.

이는 API를 감싼 생성된 래퍼가 아닙니다. 모델이 사용할 수 있게 만드는 세 가지 요소가 있습니다:

• 도구는 공개 OpenAPI 계약에서 파생됩니다. 따라서 각 도구의 입력 스키마는 실제 작업의 스키마입니다 — 열거형, 라인 항목, 제도 키 등 모두 포함됩니다. 표면이 API에서 벗어날 수 없습니다.

• 도구 포함 정책은 에이전트에게 실제로 무엇을 제공할지 결정합니다. 바이너리 다운로드, 멀티파트 업로드, 웹훅 연결, 그리고 더 이상 사용되지 않는 작업은 수동이 아닌 규칙에 따라 제외됩니다.

• 재정적 안전장치가 도구와 함께 제공됩니다: 생성된 래퍼가 놓칠 수 있는 불변 조건을 모델이 읽는 문서와, 비준수 요청이 재정 문서가 되기 전에 중지하는 사전 점검으로 모두 제공합니다.

하나의 코드베이스, 두 가지 전송 방식: 호스팅된 원격 서버 https://mcp.beel.es/mcp(Streamable HTTP + OAuth — 사용자당 한 번의 로그인, 설치할 것 없음)와, 이 저장소에서 빌드된 로컬 stdio 서버로, API 키가 작동하고 브라우저 기반 로그인이 작동하지 않는 헤드리스 사용을 위한 것입니다.

빠른 시작

https://mcp.beel.es/mcp 를 Claude, ChatGPT, Cursor 또는 VS Code에서 커넥터로 추가하고 BeeL 계정으로 로그인하세요. 설치할 것도, 처리할 API 키도 없습니다: 서버는 사용자 자신의 자격 증명으로 작동하며, OAuth 흐름은 URL에서 자동으로 발견됩니다.

# Claude Code
claude mcp add --transport http beel https://mcp.beel.es/mcp

이것이 대화형 사용을 위한 전체 설정입니다. 로컬 서버가 필요한 경우에만 계속 읽으세요.

Related MCP server: chile-invoice-mcp

로컬에서 실행하기

OAuth를 사용할 수 없는 경우 로컬 서버를 사용하세요: 송장을 발행하는 예약 작업, CI 파이프라인, 또는 브라우저 로그인을 완료할 사람이 없는 헤드리스 프로세스. 대신 API 키로 인증합니다.

Node ≥ 20 필요.

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "beel": {
      "command": "npx",
      "args": ["-y", "@beel_es/mcp"],
      "env": { "BEEL_API_KEY": "beel_sk_test_xxx" }
    }
  }
}

# Claude Code
claude mcp add beel --env BEEL_API_KEY=beel_sk_test_xxx -- npx -y @beel_es/mcp

beel_sk_test_ 접두사가 붙은 키는 실험에 안전합니다. beel_sk_live_는 실제 재정 문서를 발행합니다.

릴리스는 CI에서 npm 신뢰할 수 있는 게시를 통해 게시되므로 출처가 기록됩니다: npm은 각 빌드가 나온 정확한 커밋과 워크플로를 기록합니다. npm audit signatures로 확인하세요.

각 릴리스는 또한 MCP 레지스트리에 es.beel/mcp 로 공지되어 두 전송 방식을 모두 나열하므로, 레지스트리를 탐색하는 클라이언트는 서버를 가리키지 않아도 찾을 수 있습니다. 이름은 beel.es의 DNS 레코드로 인증되므로, 서버가 단순히 어떤 저장소에서 온 것이 아니라 우리에게서 온 것임을 나타냅니다.

io.github.beel-es/beel-mcp(v0.2.2) 아래의 이전 목록은 이름이 이동하면서 폐기되었습니다. 레지스트리 이름은 라벨이 아니라 정체성이므로, 이름 변경은 리디렉션이 아니라 새 항목입니다. 둘 다 동일한 npm 패키지와 동일한 호스팅 서버를 가리킵니다.

제공 기능

• 118개의 API 도구 — openapi/public-api.yaml에서 파생됨 — 송장, 고객, 제품, 반복 송장, 시리즈 및 세금 구성, NIF 검증, 회사.

• 4개의 합성 도구 — API에 단일 엔드포인트가 없는 것: beel_docs_search, beel_docs_get, beel_docs_list (문서 검색), 그리고 beel_get_setup_status — NIF별로 발행 전에 정확히 무엇이 누락되었는지와 다음에 취할 단 하나의 조치를 보고합니다.

• beel://guardrails/* 아래의 안전장치 리소스 — 재정 불변 조건, 그리고 beel://guardrails/errors — 각 오류 코드와 그에 필요한 조치를 담은 카탈로그. 그 요약은 제약하는 모든 도구의 설명에 통합됩니다.

• 7개의 워크플로 프롬프트 — 안전한 작업 순서가 안전을 보장하는 흐름에 대한 안전한 작업 순서를 인코딩합니다: issue-invoice (NIF 검증 → F1/F2 선택 → VeriFactu 게이트 확인 → 발행), fix-invoice (무효 vs 수정), onboard-nif, setup-representation, invite-member, connect-payments, upgrade-integration.

• 인라인 송장 PDF 뷰어 (MCP Apps): 송장 PDF를 생성하면 지원하는 호스트에서 측면 패널에 열립니다.

모든 도구와 각각에 필요한 범위의 생성된 카탈로그는 docs.beel.es/mcp/tools에 있습니다 (npm run tools:catalog).

의도적으로 도구가 아닌 것

바이너리 다운로드(PDF 미리보기, 대량 ZIP, Excel/CSV 내보내기), 멀티파트 업로드(CSV/Holded 가져오기, 서명된 PDF 제출), 웹훅 인프라, 그리고 모든 deprecated 작업. 에이전트가 이를 구동할 수 없으며, 각각은 사용 가능한 도구에 필요한 컨텍스트를 소비합니다. 규칙은 src/policy/tool-policy.ts에 있습니다.

재정 안전장치

스페인 전자 송장에는 LLM이 스키마만으로는 잘못 이해할 불변 조건이 있습니다 — 수정해야 할 송장을 무효화하거나, 간이 송장에 R1을 사용하거나, AEAT가 이미 등록한 것을 편집하는 것. 서버는 세 가지 계층으로 이를 해결하며, 그 차이가 중요합니다:

1. 자문 — src/guardrails/rules/*.md, 주제별 Markdown 파일: 송장 수명 주기, 무효 vs 수정, 송장 유형, 송장 라인, 제도 키, 시리즈 번호, NIF 검증, VeriFactu 게이트, 다중 NIF 계정. 각각은 beel://guardrails/* 아래의 MCP 리소스로 노출되며, 그 한 줄 요약은 제약하는 모든 도구의 설명에 추가되어 제약이 호출과 함께 전달됩니다.

2. 강제 — src/guardrails/validate.ts, 요청을 보내기 전에 확인되므로 잘못된 페이로드는 멱등성 키를 소비하지도 않습니다:

3. 설명 — BeeL API는 이미 잘 응답합니다: message는 호출자의 언어로 사람을 위해 작성되었고, error.details는 구체적인 내용을 전달하며, RFC 7807 type 필드는 해당 정확한 코드(약 357개)에 대한 문서 페이지로 연결됩니다. 서버는 이 모든 것을 그대로 전달하고, 응답이 전달할 수 없는 두 가지만 추가합니다: 도구 호출로서의 해결책 — 문서는 대시보드가 열린 사람을 대상으로 합니다("설정에서 시리즈 만들기"), 에이전트는 beel_set_default_series가 필요합니다 — 그리고 재시도가 도움이 될 수 있는지 여부, 이는 관리자가 필요한 403에서 에이전트가 반복하는 것을 막습니다. src/guardrails/catalog.ts에는 해당 중 하나가 적용되는 코드만 포함됩니다. 다른 것은 통과합니다. 왜냐하면 의역은 원본보다 나쁘고 원본에서 벗어날 수 있기 때문입니다. EMISSION_NOT_READY의 중첩된 blockers[]가 가장 명확한 경우입니다: 메시지도 링크도 없는 빈 문자열로 도착하며, 각각은 이를 해결하는 도구를 명명하여 다시 나옵니다.

BeeL API가 이 모든 것의 권위입니다. 모든 강제 규칙은 계약이 문서화한 거부를 반영하므로, 사전 점검은 API가 거부하는 것의 엄격한 하위 집합입니다: 실패를 더 빠르고 더 잘 설명할 수만 있을 뿐, API가 거부할 것을 허용하지는 않습니다. 서버 측 상태에 의존하는 규칙 — AEAT 인구 조사 일치, €3,000 F2 상한, 시리즈 존재 여부 — 는 의도적으로 자문으로 남아 있습니다. 로컬에서 추측하면 유효한 송장을 거부할 수 있기 때문입니다. BEEL_DISABLE_PREFLIGHT=1을 설정하면 로컬 검사를 완전히 우회할 수 있습니다.

수동으로 선별된 목록은 테스트로 고정됩니다: 카탈로그에 있는 모든 코드는 계약에 계속 나타나야 하고, 확인된 모든 operationId는 실제 도구로 계속 해석되어야 하며, 모든 안전장치 참조는 존재하는 안전장치를 가리켜야 합니다. API 이름 변경은 재정 검사를 조용히 끄는 대신 CI를 실패시킵니다.

구성

로컬 서버 전용

공유

모든 기본값은 src/shared/defaults.ts에 있으며, 어디에도 중복 하드코딩되지 않습니다. 원격 배포 변수는 DEPLOY.md에 문서화되어 있습니다.

서버는 자격 증명 없이도 시작되어 도구 목록을 표시합니다. API 도구가 실제로 호출될 때만 오류가 발생합니다. POST 요청은 요청 자체에서 파생된 안정적인 Idempotency-Key를 전달하므로, 에이전트가 "인보이스 생성"을 재시도해도 두 번째 인보이스가 생성될 수 없습니다.

자체 호스팅

원격 서버는 Cloudflare Workers에서 실행됩니다. KV 네임스페이스, BeeL이 등록해야 하는 OAuth 클라이언트, 관련 시크릿에 대해서는 DEPLOY.md를 참조하세요.

개발

npm ci
npm run dev          # stdio server from source
npm test             # vitest
npm run typecheck    # both the Node and the Worker configs
npm run build        # single-file bundle to dist/index.js
npm run inspect      # MCP Inspector against the local build
npm run spec:verify  # the vendored contract still matches its lock

openapi/public-api.yaml은 API 계약의 생성된 사본이며, openapi/spec.lock.json은 버전, 작업 수 및 해시를 기록합니다. 두 파일이 일치하지 않으면 CI가 실패하며, 이는 벤더 계약의 정합성을 유지하는 방법입니다. CONTRIBUTING.md를 참조하세요.

BeeL 개발자 생태계의 나머지

아래의 모든 것은 동일한 OpenAPI 계약에서 파생되므로, 어휘(인보이스 유형, 레짐 키, 시리즈, VeriFactu 상태)는 어디서든 동일합니다.

FAQ

BeeL MCP 서버란 무엇인가요? 스페인 VeriFactu 전자 인보이스 발행을 AI 에이전트가 호출할 수 있는 도구로 노출하는 MCP 서버입니다. Claude, ChatGPT, Cursor 또는 VS Code가 고객을 생성하고, F1/F2 인보이스를 발행하고, AEAT에 등록하고, R1–R5 정정을 대신 게시할 수 있습니다.

VeriFactu 인보이스 발행을 Claude / ChatGPT / Cursor에 어떻게 연결하나요? https://mcp.beel.es/mcp를 커넥터로 추가하고 BeeL 계정으로 로그인하세요. 빠른 시작을 참조하세요. 설치할 것이 없고, 대화형 사용을 위해 API 키를 붙여넣을 필요도 없습니다.

실제로 VeriFactu를 준수하나요? 네. 인보이스는 VeriFactu에 따라 AEAT에 등록되며, 번호 매기기와 시리즈는 규정을 따르고, 재정 가드레일은 비준수 요청이 재정 문서가 되기 전에 차단합니다.

VeriFactu 또는 TicketBAI? 이 서버는 국가 AEAT 시스템인 VeriFactu를 대상으로 합니다. TicketBAI(바스크 지방 레짐)는 범위에 포함되지 않습니다.

AI 에이전트 없이 사용할 수 있나요? 네. 표준 MCP 서버이므로 MCP를 지원하는 모든 클라이언트에서 작동하며, 동일한 인보이스 발행 표면을 REST API, CLI 및 n8n 노드로도 사용할 수 있습니다.

기여

버그 리포트와 풀 리퀘스트를 환영합니다. 프로젝트 구성과 중요한 규칙에 대해서는 CONTRIBUTING.md를 참조하세요. 보안 문제는 공개 이슈가 아닌 security@beel.es 로 보내주세요. SECURITY.md를 참조하세요.

라이선스

MIT © BeeL.