한국 공휴일 MCP

커넥터 URL: https://korea-holiday-mcp.vercel.app/api/mcp 소개 페이지: https://korea-holiday-mcp.vercel.app

Claude에 URL 하나만 등록하면 한국 공휴일·대체공휴일·영업일 계산을 정확하게 처리하는 MCP 서버입니다. 인증이 없는 공개 커넥터라서 설치·로그인·API 키가 필요 없습니다.

왜 필요한가

LLM은 날짜 산수에 약합니다. 한국 공휴일은 음력 명절(설날·추석·부처님오신날)과 대체공휴일 규칙이 얽혀 있어서 모델이 그럴듯한 오답을 내기 쉽습니다. 실제로 자주 틀리는 지점:

• 현충일은 대체공휴일이 없습니다. 2027년 6월 6일은 일요일이지만 6월 7일은 정상 근무일입니다. 현충일은 국경일이 아니라서 「관공서의 공휴일에 관한 규정」 제3조 적용 대상이 아닙니다.

• 설날·추석은 일요일과 겹칠 때만 대체공휴일이 생깁니다. 토요일과 겹쳐도 늘어나지 않습니다.

• 제헌절이 2026년부터 다시 공휴일입니다. 2008년 제외 후 18년 만의 복귀라 학습 데이터에 거의 없습니다.

이 서버는 날짜 표를 외워둔 게 아니라 법령을 코드로 구현해서, 매번 결정적으로 같은 답을 냅니다.

연결 방법

Claude 웹 · 데스크톱 앱

1. 설정 → 커넥터로 이동

2. 커스텀 커넥터 추가 클릭

3. 이름 한국 공휴일, URL에 https://korea-holiday-mcp.vercel.app/api/mcp 입력

4. 대화창의 도구 메뉴에서 켜기

인증이 없는 공개 서버라 로그인 단계가 나오지 않습니다. 조직 관리자용 커넥터로 등록하면 OAuth를 기대하는 화면이 나올 수 있으니 개인 커넥터로 추가하세요.

Claude Code

claude mcp add --transport http korea-holiday https://korea-holiday-mcp.vercel.app/api/mcp

설정 파일을 직접 쓸 때

{
  "mcpServers": {
    "korea-holiday": {
      "type": "http",
      "url": "https://korea-holiday-mcp.vercel.app/api/mcp"
    }
  }
}

도구

공통 옵션:

• includeLaborDay (기본 false) — 근로자의 날(5/1)을 휴일로 계산할지. 근로자의 날은 관공서 공휴일이 아니라 근로기준법상 유급휴일이라 기본값에서는 영업일로 봅니다.

• saturdayIsBusinessDay (기본 false) — 토요일을 영업일로 계산할지.

데이터 근거와 한계

근거 법령: 「관공서의 공휴일에 관한 규정」 제2조(공휴일)·제3조(대체공휴일)

대체공휴일 규칙은 시행일을 반영해서 연도별로 다르게 적용됩니다.

조회 범위: 2015~2050년. 음력 데이터가 2050년까지만 있어서 그 이후는 오류를 반환합니다.

포함하지 않는 것

• 회사별 창립기념일, 업종별 휴무일

• 확정되지 않은 미래의 임시공휴일·선거일

임시공휴일과 선거일은 규칙으로 예측할 수 없어 확정·공포된 것만 lib/overrides.ts에 수동 등재합니다. 새로 지정되면 한 줄 추가하고 npm run verify를 돌리면 됩니다.

민간 달력 사이트와 다를 수 있는 지점

일부 공휴일 정리 사이트는 2027년 6월 6일(일) 현충일에 대해 6월 7일을 대체공휴일로 표시합니다. 이 서버는 법령을 따라 대체공휴일 없음으로 계산합니다. 2021년 인사혁신처 개정 당시 대체공휴일 대상에서 신정·현충일이 명시적으로 제외됐고, 이후 2023년 개정으로 추가된 것은 부처님오신날과 성탄절뿐입니다. 실제로 2021년 6월 6일(일)에도 대체공휴일은 없었습니다.

중요한 의사결정에는 관보나 인사혁신처 공고로 한 번 더 확인하세요. 계산 결과에 이상이 있으면 이슈로 알려주세요.

검증

규칙 엔진 결과를 공개 자료(2024~2027년)와 대조합니다.

npm run verify

타임존에 관계없이 같은 결과가 나오는지도 확인합니다. 모든 날짜 연산은 UTC 자정 기준으로만 처리하고, "오늘"은 KST로 계산합니다.

개발

npm install
npm run dev        # http://localhost:3000
npm run verify     # 공휴일 규칙 검증
npm run typecheck
npm run build

MCP Inspector로 도구를 직접 찔러볼 수도 있습니다.

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP / URL: http://localhost:3000/api/mcp

구조

app/
  api/mcp/route.ts   MCP 서버 (도구 6개 등록)
  page.tsx           랜딩 + 연결 가이드
lib/
  date.ts            타임존 안전 날짜 유틸
  holidays.ts        공휴일 규칙 엔진 (법령 구현)
  overrides.ts       임시공휴일·선거일 수동 테이블
  format.ts          응답 텍스트 포맷터
scripts/
  verify.ts          공개 자료 대조 검증

배포

Vercel에 이 저장소를 연결하면 그대로 배포됩니다. 환경 변수는 필요 없습니다. 커넥터 URL은 배포 도메인 뒤에 /api/mcp를 붙인 주소이고, 랜딩 페이지가 자기 도메인을 읽어 자동으로 올바른 URL을 보여줍니다.

개인정보

날짜 문자열만 받아서 계산 결과를 돌려줍니다. 사용자 데이터를 저장하거나 외부로 보내지 않습니다.

라이선스

MIT