CanGoal 로고
CanGoal

조용히 목표 달성을 도와주는 동반자

🤖 MCP (모델 컨텍스트 프로토콜)

CanGoal에는 MCP (Model Context Protocol) 서버가 내장되어 있어, Claude Desktop, Cursor, ChatGPT Desktop과 같은 AI 어시스턴트가 안전한 로컬 연결을 통해 목표, 작업, 타이밍 세션, 노트, 통계를 직접 읽고 관리할 수 있습니다.

  • 프로토콜: MCP 2025-06-18 + JSON-RPC 2.0
  • 전송 방식: stdio 전용 (stdin/stdout) — HTTP나 WebSocket 서버는 사용하지 않습니다
  • 도구: 22개 (Goal 6 / Task 6 / Timing 3 / Note 5 / Stats 2)
  • 플랫폼: macOS 전용 (iOS 프로세스는 데스크톱 클라이언트에서 실행할 수 없습니다)

MCP는 CanGoal 앱 안에 포함된 별도의 도우미 실행 파일로 동작하므로 메인 앱을 방해하지 않습니다 — GUI와 AI 어시스턴트를 동시에 실행할 수 있습니다.

MCP로 AI가 할 수 있는 일

연결되면 AI 어시스턴트는 다음을 수행할 수 있습니다:

  • 데이터 읽기 — 목표, 작업, 타이밍 기록, 노트, 통계를 조회합니다.
  • 생성 및 편집 — 목표와 작업을 추가하고, 작업을 완료하고, 집중 타이머를 시작/중지하고, 노트를 추가합니다.
  • 진행 상황 추적 — 통계와 목표별 정량화 진행 상황을 조회합니다.

AI가 수행하는 모든 작업은 CanGoal 앱과 완전히 동일한 비즈니스 로직을 거치므로, 연속 달성 기록, 위젯, 알림, CloudKit 동기화가 모두 동일하게 동작합니다.

AI 클라이언트 연결하기

MCP 도우미는 설치된 앱 내의 다음 경로에 있습니다:

/Applications/CanGoal.app/Contents/Helpers/CanGoalMCP.app/Contents/MacOS/CanGoalMCP

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집합니다:

{
  "mcpServers": {
    "cangoal": {
      "command": "/Applications/CanGoal.app/Contents/Helpers/CanGoalMCP.app/Contents/MacOS/CanGoalMCP",
      "args": []
    }
  }
}

Claude Desktop을 다시 시작합니다. 도구 메뉴에 cangoal 서버의 22개 도구가 표시됩니다.

Cursor

Settings → MCP Servers → Add new MCP Server로 이동합니다:

  • Type: command
  • Name: cangoal
  • Command: /Applications/CanGoal.app/Contents/Helpers/CanGoalMCP.app/Contents/MacOS/CanGoalMCP

ChatGPT Desktop

Settings → Connectors → Add new connector로 이동하여 Claude Desktop과 동일한 JSON을 사용합니다.

사용 가능한 도구 (22)

Goal (6)

  • list_goals — 모든 목록 조회, 상태 / 활성 여부로 필터링 가능
  • get_goal — 목표 상세 정보 조회 (진행률, 통계 요약)
  • create_goal — 목표 생성 (이름, 유형, 색상, 마감일, 정량 목표)
  • update_goal — 목표 필드 수정
  • delete_goal — 목표 소프트 삭제
  • list_goal_templates — 사용 가능한 목표 템플릿 목록 조회

Task (6)

  • list_tasks — 작업 목록 조회, 목표 / 날짜 / 상태로 필터링
  • get_task — 작업 상세 정보 조회 (체크리스트, 연속 달성 기록)
  • create_task — 목표 아래에 작업 생성
  • update_task — 작업 필드 수정
  • complete_task — 작업을 완료로 표시 (GUI와 동일하게 연속 달성 기록 / 위젯 / 알림 트리거)
  • delete_task — 작업 삭제

Timing (3)

  • start_timing — 작업에 대한 집중 세션 시작 (스톱워치 또는 뽀모도로)
  • stop_timing — 현재 세션 중지, TimingRecord + GoalEvent 기록
  • list_timing_records — 타이밍 기록 조회

Note (5)

  • list_notes — 목표 / 작업 / 날짜별로 노트 조회
  • get_note — 노트의 전체 내용 조회
  • add_note — 목표 또는 작업에 텍스트 노트 추가
  • update_note — 노트 수정
  • delete_note — 노트 삭제

Stats (2)

  • get_statistics — 전체 통계 (오늘 완료 개수, 연속 달성 기록, 총 타이밍, 목표 개요)
  • get_goal_progress — 목표에 대한 정량화 진행 상황 + 작업별 기여도

개인정보 및 보안

  • MCP는 stdio를 통해 완전히 로컬에서 실행됩니다 — 데이터가 어떠한 추가 서버를 거치지도 않습니다.
  • 도우미는 CanGoal 앱과 동일한 Core Data 저장소(App Group 컨테이너 경유)를 읽고 쓰며, App Sandbox로 보호됩니다.
  • MCP 연결 자체는 어떠한 개인 데이터도 수집하거나 전송하지 않으며, 이미 CanGoal 데이터베이스에 있는 데이터에만 접근합니다.
  • CloudKit 동기화가 기기 간과 마찬가지로 MCP 도우미와 GUI 사이에서도 데이터를 일관되게 유지합니다.

문제 해결

  • AI 클라이언트가 도구를 볼 수 없음 — 명령어 경로가 --mcp가 포함된 이전 메인 바이너리를 가리킴. 해결: Contents/Helpers/CanGoalMCP.app/... 아래의 도우미 경로를 사용하고, --mcp 인수를 제거하세요.
  • 도구가 isError: true 반환 — 비즈니스 오류 (리소스를 찾을 수 없음 / 상태 충돌 / 잘못된 매개변수). 해결: content[0].text의 메시지를 확인하세요.
  • 도구가 JSON-RPC 오류 -32602 반환 — 잘못된 도구 이름 또는 스키마 불일치. 해결: tools/list를 실행하여 스키마를 다시 확인하세요.
  • 도우미가 빈 데이터를 읽음 — Core Data 저장소 불일치. 해결: 앱이 설치되어 있고 데이터가 있는지 확인하세요. 도우미는 동일한 저장소를 공유합니다.

참고 사항

  • MCP는 macOS 전용입니다 — iOS 앱은 데스크톱 AI 클라이언트에서 실행할 수 없습니다.
  • stdio 전송 방식만 지원됩니다 (HTTP / WebSocket / SSE는 지원되지 않음).
  • 하나의 도우미 프로세스가 한 번에 하나의 클라이언트 세션만 서비스합니다.
  • resources/* 및 prompts/* MCP 메서드는 지원되지 않으며, tools/*만 지원됩니다.
🤖 MCP (모델 컨텍스트 프로토콜) – CanGoal