MCP Fantastical 서버

Fantastical을 위한 MCP 서버 - macOS용 강력한 캘린더 앱입니다.

왜 이 서버를 사용해야 하나요?

• 자연어 이벤트 생성 - Fantastical의 강력한 자연어 파싱 기능 사용 ("내일 오후 3시에 John과 미팅")

• 일정 보기 - 대화를 떠나지 않고 오늘의 이벤트나 예정된 약속 확인

• 빠른 캘린더 접근 - Fantastical에서 원하는 날짜로 즉시 이동

• 캘린더 인식 AI - Claude가 사용자의 가용성과 일정 맥락을 이해하도록 지원

• 제로 구성 - 기존 Fantastical 및 캘린더 설정과 바로 연동

Related MCP server: Apple Calendar MCP Server

기능

사전 요구 사항

• macOS (Fantastical은 macOS 전용)

• Node.js 18 이상

• Fantastical 설치됨

• 터미널/Claude에 대한 캘린더 접근 권한

설치

npm 사용 (권장)

npx mcp-fantastical

소스에서 설치

git clone https://github.com/aplaceforallmystuff/mcp-fantastical.git
cd mcp-fantastical
npm install
npm run build

구성

API 키가 필요하지 않습니다. 이 서버는 AppleScript를 사용하여 Fantastical 및 캘린더 앱과 통신합니다.

Claude Desktop용

Claude Desktop 설정 파일에 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Claude Code용

~/.claude.json에 추가하세요:

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

권한

처음 실행 시 다음 권한을 부여해야 할 수 있습니다:

손쉬운 사용 (URL 스킴을 통한 이벤트 생성용):

1. 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용

2. 허용된 목록에 터미널(또는 사용하는 터미널 앱) 추가

전체 캘린더 접근 권한 (이벤트 읽기용):

네이티브 헬퍼는 임시 서명된 .app 번들(FantasticalHelper.app)로 제공됩니다. MCP 서버가 처음으로 캘린더 데이터를 읽을 때, macOS는 **"FantasticalHelper"**가 전체 캘린더 접근 권한을 요청한다는 일회성 알림을 표시합니다. 이를 승인하세요.

알림을 놓쳤거나 나중에 다시 권한을 부여해야 하는 경우:

1. 시스템 설정 → 개인정보 보호 및 보안 → 캘린더

2. FantasticalHelper 활성화

참고: 이전 버전에서는 원시 헬퍼 바이너리를 제공했으나, Claude Desktop에서 실행 시 macOS가 TCC 권한을 부여할 수 없어 알림이 표시되지 않고 접근이 조용히 거부되었습니다(#6). 번들 및 서명된 헬퍼가 이 문제를 해결합니다.

사용 예시

이벤트 생성

• "내일 오후 2시에 팀 미팅 잡아줘"

• "금요일 오전 10시에 치과 예약을 개인 캘린더에 추가해줘"

• "매주 월요일 오전 9시에 반복되는 스탠드업 미팅 생성해줘"

• "다음 주 화요일 오후는 집중 업무 시간으로 비워줘"

일정 보기

• "오늘 내 일정은 뭐야?"

• "다음 주 내 일정을 보여줘"

• "내일 어떤 미팅이 있어?"

• "금요일 오후에 시간 돼?"

탐색

• "다음 주 월요일로 캘린더 열어줘"

• "Fantastical에서 12월 25일을 보여줘"

• "캘린더에서 다음 주로 이동해줘"

검색

• "Sarah와의 모든 미팅 찾아줘"

• "치과 예약 검색해줘"

• "프로젝트 검토 미팅 찾아봐"

사용 가능한 도구

개발

# Watch mode for development
npm run watch

# Build TypeScript
npm run build

# Run locally
node dist/index.js

문제 해결

"AppleScript error: Not authorized to send Apple events"

손쉬운 사용 권한을 부여하세요:

1. 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용을 엽니다.

2. 자물쇠를 클릭하여 변경을 허용합니다.

3. 터미널(또는 사용하는 터미널 앱)을 추가하고 활성화합니다.

캘린더 권한 오류 또는 Claude Desktop에서 "Calendar access denied"

macOS TCC 권한은 Claude Desktop → npx → node → 헬퍼 체인을 통해 상속되지 않습니다. 네이티브 헬퍼는 임시 서명된 FantasticalHelper.app 번들로 래핑되어 macOS가 캘린더 권한을 부여할 수 있는 안정적인 코드 ID를 갖도록 합니다.

해결 방법:

1. FantasticalHelper가 요청하는 일회성 시스템 알림을 찾아 승인하세요. 다른 창 뒤에 가려졌다면 MCP 클라이언트를 재시작하고 다시 시도하세요.

2. 시스템 설정 → 개인정보 보호 및 보안 → 캘린더에서 FantasticalHelper를 활성화하세요.

3. 소스에서 실행 중이라면 번들을 다시 빌드하세요: npm run build:native.

4. 어떤 이유로든 번들에 코드 서명이 누락된 경우 다시 서명하세요: codesign --force --sign - dist/native/FantasticalHelper.app.

"Error: This MCP server only works on macOS"

Fantastical은 macOS 애플리케이션이므로 이 서버는 macOS가 필요합니다. AppleScript를 사용하여 Fantastical 및 캘린더 앱과 통신합니다.

이벤트가 표시되지 않음

• Fantastical이 iCloud/캘린더와 동기화 중인지 확인하세요.

• Calendar.app이 동일한 캘린더에 접근할 수 있는지 확인하세요.

• 이벤트가 올바른 캘린더에 생성되었는지 확인하세요.

• 전체 캘린더 접근 권한을 부여하세요(위 참조).

Fantastical이 열리지 않음

• Fantastical이 설치되어 있는지 확인하세요.

• Fantastical을 수동으로 먼저 열어보세요.

• Fantastical 설정에서 URL 스킴이 활성화되어 있는지 확인하세요.

라이선스

MIT - 자세한 내용은 LICENSE를 참조하세요.

링크

• Fantastical - 공식 Fantastical 웹사이트

• Model Context Protocol - MCP 사양

• GitHub 저장소