CalDAV MCP 포워더

완전히 상태 비저장(stateless)인 Model Context Protocol 서버로, Cloudflare Workers에서 CalDAV 서버로의 캘린더 작업을 전달합니다.

소스 코드 및 배포 가이드는 GitHub 저장소에서 확인할 수 있습니다.

상태: 기능적인 첫 번째 릴리스입니다. Worker는 캘린더 검색, 이벤트 목록/검색, 이벤트 조회, 생성, 업데이트, 삭제 및 사용 가능/바쁨(free/busy) 쿼리를 지원합니다.

세 단계로 연결하기

1. 브라우저에서 https://caldavmcp.anpc.work를 엽니다.

2. CalDAV 서버, 사용자 이름 및 앱 비밀번호를 입력한 후 Test connection을 클릭합니다. Calendar URL은 비워두면 캘린더가 자동으로 검색됩니다.

3. 원하는 경우 기본 캘린더를 선택하고, 보안 토큰을 생성한 후 생성된 MCP URL 또는 구성을 AI 어시스턴트에 복사합니다.

공개 페이지는 기본적으로 만료되지 않는 암호화된 토큰을 생성하여 한 번 설정하면 계속 연결됩니다. 필요에 따라 더 짧은 수명을 선택할 수도 있습니다. 자격 증명은 HTTPS를 통해 Worker로 전송되어 암호화되며, 브라우저에서 디코딩되지 않습니다. 토큰을 폐기해야 하는 경우 CONNECTION_TOKEN_KEY를 교체하세요.

어시스턴트는 이벤트를 나열, 검색, 읽기, 생성, 업데이트, 삭제하고 사용 가능/바쁨 정보를 쿼리할 수 있습니다. 모든 요청은 독립적이며, 캘린더, 자격 증명 또는 세션이 저장되지 않습니다.

Related MCP server: mcp-labrat

보안 모델

원시 비밀번호, 앱 비밀번호 또는 액세스 토큰을 URL에 직접 넣지 마십시오. URL은 브라우저 기록, 리버스 프록시, 분석 시스템 및 액세스 로그에 남을 수 있습니다.

연결 토큰은 AES-GCM으로 암호화된 값입니다.

POST https://caldavmcp.anpc.work/mcp/<encrypted-connection-token>

토큰은 다음과 같은 연결 세부 정보를 나타냅니다.

{
  "serverUrl": "https://caldav.example.com",
  "calendarUrl": "https://caldav.example.com/calendars/user/work/",
  "username": "user@example.com",
  "password": "app-password",
  "expiresAt": 1797700000
}

Worker는 각 토큰을 한 번의 요청에 대해 복호화하고 이후 연결 세부 정보를 폐기합니다. 토큰은 생성 시 만료를 선택하지 않는 한 만료되지 않습니다. CONNECTION_TOKEN_KEY를 교체하면 이전 키로 생성된 모든 토큰이 폐기됩니다. 이벤트 및 사용 가능/바쁨 URL은 구성된 CalDAV 서버에 속해야 합니다. Worker 비밀로 구성하세요. 키는 128비트, 192비트 또는 256비트 AES 키를 포함하는 URL 안전 base64여야 합니다.

기본 계정 비밀번호보다는 제공업체별 앱 비밀번호 또는 OAuth 액세스 토큰을 선호하세요. 토큰이나 자격 증명을 이 저장소에 커밋하지 마십시오.

MCP 클라이언트 연결하기

Worker를 배포한 후, Worker URL로 MCP 클라이언트를 구성하세요. 정확한 구성은 클라이언트에 따라 다르지만, 엔드포인트는 다음과 같습니다.

https://caldavmcp.anpc.work/mcp/<encrypted-connection-token>

원격 HTTP 서버를 허용하는 MCP 클라이언트 구성의 경우, 엔드포인트를 서버 URL로 사용하세요. 예를 들어:

{
  "mcpServers": {
    "caldav": {
      "type": "http",
      "url": "https://caldavmcp.anpc.work/mcp/<encrypted-connection-token>"
    }
  }
}

위의 예제 토큰을 실제 클라이언트에 붙여넣지 마십시오. 의도한 CalDAV 계정 및 캘린더에 대해 생성된 토큰으로 교체하세요.

어시스턴트는 다음과 같은 도구를 호출할 수 있습니다.

• list_calendars

• list_events

• search_events

• get_event

• create_event

• update_event

• delete_event

어시스턴트가 처리할 수 있는 요청 예시:

• "내 업무 캘린더에 내일 일정이 뭐가 있지?"

• "다음 주 화요일 10시에 치과 예약을 만들어 줘."

• "오후 3시 회의를 금요일로 옮겨 줘."

• "'프로젝트 검토'라는 제목의 이벤트를 취소해 줘."

• "분기별 계획 회의를 언급하는 모든 이벤트를 찾아 줘."

어시스턴트는 특히 이벤트 삭제와 같은 중요한 파괴적 작업을 수행하기 전에 사용자에게 확인을 받아야 합니다.

도구 출력 형식

도구 응답은 다음 작업에 필요한 정보만 포함하는 간결한 JSON을 사용합니다.

• 캘린더 목록에는 url과 함께 사용 가능한 displayName, description, timezone, color가 포함됩니다.

• 이벤트 목록 및 get_event에는 url, 선택적 etag, 현재 iCalendar data가 포함됩니다.

• create_event는 생성된 이벤트 url을 반환합니다.

• update_event는 업데이트된 이벤트 url을 반환합니다.

• delete_event는 삭제된 이벤트 url과 deleted: true를 반환합니다.

• get_free_busy는 사용 가능/바쁨 iCalendar data만 반환합니다.

응답에는 HTTP 상태 코드, 원시 CalDAV 메타데이터 또는 프레젠테이션 형식이 포함되지 않습니다.

배포

의존성 설치:

npm install

Worker를 로컬에서 실행:

npm run dev

프로젝트 타입 검사:

npm run typecheck

단위 테스트 실행

npm test

커버리지 포함 테스트 실행

npm run coverage

커버리지 임계값은 구문(statements), 라인(lines), 함수(functions)에 대해 90%, 분기(branches)에 대해 85%로 적용됩니다. 현재 단위 테스트 가능한 소스 모듈은 네 가지 범주 모두에서 100%를 보고합니다. Cloudflare Worker 진입점은 Workers 런타임과 외부 CalDAV 서비스가 필요하므로 제외됩니다. 배포된 상태 또는 wrangler dev 스모크 테스트로 검증하세요.

Cloudflare Workers에 배포:

npx wrangler login
npm run deploy

Worker는 caldavmcp.anpc.work의 Cloudflare Custom Domain으로 구성됩니다. Wrangler는 동일한 Cloudflare 계정에서 영역이 활성화되면 도메인과 인증서를 생성합니다. 배포 전에 필요한 비밀을 설정하세요.

npx wrangler secret put CONNECTION_TOKEN_KEY
npm run deploy

도메인은 Cloudflare DNS에서 활성화되어야 합니다. caldavmcp.anpc.work에 대해 충돌하는 CNAME 레코드를 추가하지 마십시오. Custom Domain이 DNS 레코드를 관리합니다.

암호화 키를 Cloudflare Worker 비밀로 설정:

npx wrangler secret put CONNECTION_TOKEN_KEY

로컬 개발의 경우 .dev.vars.example에서 .dev.vars를 만들고 자리 표시자를 생성된 키로 교체하세요. Wrangler는 npm run dev 실행 시 .dev.vars를 자동으로 로드합니다. 해당 파일을 커밋하지 마십시오.

cp .dev.vars.example .dev.vars
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

암호화 키를 wrangler.jsonc, 소스 코드 또는 클라이언트 구성에 절대 넣지 마십시오.

사용 가능한 도구

모든 도구는 토큰의 calendarUrl로 선택된 캘린더에서 작동하거나, 적절한 경우 명시적인 calendarUrl을 허용합니다.

날짜는 ISO 8601 문자열(예: 2026-08-20T10:00:00Z)이어야 합니다. 이벤트 업데이트는 현재 iCalendar data가 필요하므로 알 수 없는 제공업체별 속성이 보존됩니다.

에이전트를 위한 도구 동작

• 사용 가능한 캘린더 URL을 모를 경우 먼저 list_calendars를 호출하세요.

• list_events 및 search_events에는 start와 end가 필요합니다. 명시적인 calendarUrl은 하나의 캘린더를 선택합니다. 없으면 토큰에 구성된 캘린더가 사용되며, 구성된 캘린더가 없으면 모든 캘린더가 검색됩니다.

• search_events는 각 이벤트의 iCalendar 데이터에서 대소문자를 구분하지 않는 텍스트 검색을 수행하며, 이벤트 제목만 검색하지 않습니다.

• get_event에는 이벤트의 현재 HTTPS 객체 URL이 필요합니다.

• create_event에는 summary, start, end가 필요합니다. 캘린더 선택은 명시적 URL, 토큰 캘린더, 그다음 첫 번째 사용 가능한 캘린더 순입니다.

• update_event에는 현재 이벤트 data가 필요합니다. 생략된 필드는 보존되므로 변경할 필드만 보내세요.

• delete_event는 이벤트를 영구적으로 제거합니다. 먼저 사용자에게 삭제를 확인하고, 사용 가능한 경우 현재 ETag를 전달하세요.

• get_free_busy는 요청된 범위에 대한 iCalendar 사용 가능/바쁨 데이터를 반환하며 이벤트 세부 정보를 나열하지 않습니다.

상태 비저장 요청 흐름

MCP client
   |
   | POST /mcp/<encrypted-token>
   v
Cloudflare Worker
   | decrypt token in memory
   | create request-scoped CalDAV client
   | perform one operation
   | discard credentials and response data
   v
CalDAV server

이 Worker는 캘린더 데이터나 MCP 세션 상태를 유지하지 않습니다. 요청 본문, 자격 증명 및 CalDAV 응답은 요청 중에만 존재합니다.

제공업체 참고 사항

CalDAV 구현은 다릅니다. 앱 비밀번호 또는 제공업체별 엔드포인트가 필요할 수 있습니다.

• Nextcloud: 일반적으로 앱 비밀번호와 캘린더 컬렉션 URL을 지원합니다.

• Fastmail: 앱별 비밀번호와 Fastmail에서 제공하는 CalDAV 엔드포인트를 사용하세요.

• iCloud: 일반적으로 앱별 비밀번호와 계정의 CalDAV 엔드포인트가 필요합니다.

• Google Calendar: 기본 CalDAV 지원이 제한적입니다. CalDAV 호환성이 충분하지 않으면 대신 Google API를 사용하세요.

항상 대상 제공업체에서 캘린더 검색, 반복 이벤트, 시간대, 참석자, ETag 및 삭제 동작을 테스트하세요.

기술 스택

• Cloudflare Workers

• TypeScript

• @modelcontextprotocol/sdk

• tsdav

• ical.js

• zod

제한 사항

이 서비스는 요청을 전달할 뿐 캘린더 동기화 서비스가 되지 않습니다. 로컬 이벤트 인덱스를 유지하지 않으며, 캘린더 간 이벤트 중복을 제거하지 않고, 나중에 실행할 작업을 대기열에 넣지 않습니다. CalDAV 제공업체를 사용할 수 없는 경우, 영구 저장소에서 재시도 없이 요청이 실패합니다.