@odyssey365/mcp-server

Odyssey — 일상의 OS — 의 할일/메모/타임라인을 MCP 호환 AI 클라이언트에서 관리할 수 있게 해주는 MCP 서버입니다.

지원 클라이언트

| 클라이언트 | 설정 파일 | 최상위 키 | SKILL.md | |---|---|---|---| | Claude Code (글로벌) | ~/.claude/settings.json | mcpServers | ✅ ~/.claude/skills/ | | Claude Code (프로젝트) | .claude/settings.json | mcpServers | ✅ .claude/skills/ | | Claude Desktop | 플랫폼별 config | mcpServers | ✅ ~/.claude/skills/ | | Cursor | ~/.cursor/mcp.json 또는 .cursor/mcp.json | mcpServers | ✅ ~/.cursor/skills/ | | VS Code | ~/Library/Application Support/Code/User/mcp.json (darwin) 등 | servers | ❌ (MCP prompts만) | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | ✅ ~/.codeium/windsurf/skills/ | | Antigravity | ~/.gemini/antigravity/mcp_config.json | mcpServers | ❌ |

VS Code와 Antigravity는 SKILL.md 슬래시 명령 시스템이 없어 MCP 도구만 노출됩니다. odyssey-mcp install은 각 대상에 맞는 JSON 구조로 자동 기록합니다.

빠른 시작

1. Odyssey 앱에서 API Key 생성

Odyssey 앱 → 설정 → MCP 연동 → API Key 관리 → + 버튼으로 새 키 발급.

발급된 키는 odk_ 로 시작하는 20자 문자열입니다. 이 순간에만 확인 가능하므로 안전한 곳에 저장하세요.

2. 대화형 설치 (추천)

npx -y @odyssey365/mcp-server@latest install

API Key 입력 → 글로벌 설치 → 설정 파일 자동 등록 → 스킬 설치까지 한 번에 완료됩니다.

제거하려면:

npx -y @odyssey365/mcp-server@latest uninstall

설정 파일에서 odyssey 항목과 설치된 슬래시 스킬을 제거하고, 원하면 글로벌 npm 패키지도 함께 삭제합니다 (설정 파일은 .bak 백업이 남습니다).

3. 수동 등록 (직접 설정)

먼저 글로벌 설치:

npm i -g @odyssey365/mcp-server

그 후 설정 파일에 등록:

Claude Code — ~/.claude/settings.json 또는 프로젝트의 .claude/settings.json:

{
  "mcpServers": {
    "odyssey": {
      "command": "odyssey-mcp",
      "args": [],
      "env": {
        "ODYSSEY_API_KEY": "odk_여기에_발급받은_키"
      }
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "odyssey": {
      "command": "odyssey-mcp",
      "args": [],
      "env": {
        "ODYSSEY_API_KEY": "odk_여기에_발급받은_키"
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json (글로벌) 또는 프로젝트의 .cursor/mcp.json:

{
  "mcpServers": {
    "odyssey": {
      "command": "odyssey-mcp",
      "args": [],
      "env": {
        "ODYSSEY_API_KEY": "odk_여기에_발급받은_키",
        "ODYSSEY_AUTO_UPDATE": "1"
      }
    }
  }
}

VS Code — ~/Library/Application Support/Code/User/mcp.json (macOS 글로벌) 또는 프로젝트의 .vscode/mcp.json. ⚠️ VS Code는 최상위 키가 servers입니다 (다른 클라이언트의 mcpServers와 다름):

{
  "servers": {
    "odyssey": {
      "command": "odyssey-mcp",
      "args": [],
      "env": {
        "ODYSSEY_API_KEY": "odk_여기에_발급받은_키",
        "ODYSSEY_AUTO_UPDATE": "1"
      }
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "odyssey": {
      "command": "odyssey-mcp",
      "args": [],
      "env": {
        "ODYSSEY_API_KEY": "odk_여기에_발급받은_키",
        "ODYSSEY_AUTO_UPDATE": "1"
      }
    }
  }
}

Antigravity — ~/.gemini/antigravity/mcp_config.json: Windsurf와 동일한 mcpServers 구조.

4. 클라이언트 재시작

재시작하면 odyssey MCP 서버가 자동 연결됩니다. 자연어로 요청해 보세요:

"OdysseyProduct 카테고리 할일 목록 보여줘"

"오늘 한 작업을 메모로 저장해줘"

"내 프로젝트 중에서 경제학 관련된 거 상세 보여줘"

제공하는 Tool (11개)

카테고리

• list_categories — 카테고리 목록 조회 (이름 필터)

할일

• list_todos — 카테고리·상태·오늘/전체·태그 필터 조회
• get_todo — 상세 조회 (체크리스트/달성조건 포함)
• create_todo — 할일 생성 (done 상태로 바로 생성 가능)
• update_todo — 할일 수정
• complete_todo — 완료 처리 (타임라인 이벤트 자동 생성)

메모 / 일기

• get_memo — 메모 상세 (plain text로 변환)
• create_memo — 메모 생성 (plain text → Quill Delta 자동 변환, 타임라인 이벤트 자동 생성)

프로젝트

• list_projects — 프로젝트 목록
• get_project — 상세 + 포함 아이템(items[]) 평탄화
• get_project_components — 원본 components/links까지 포함한 상세
• create_project — 새 프로젝트(빈 보드) 생성. title 필수, categoryName/tags/emoji/memo 선택
• add_project_component — 컴포넌트 추가 (order 자동할당 or 끼워넣기 shift)
• update_project_component — 컴포넌트 수정. containItems는 mode: 'append' | 'replace'
• delete_project_component — 컴포넌트 제거 (참조 links 함께 정리)
• add_daily_tile — 날짜별 itemTile 생성 (YYYY-MM-DD + todoUids/memoUids)

설정

• get_setup_template — CLAUDE.md 섹션 템플릿 반환 (프로젝트별 맞춤 연동 가이드 생성)

주요 워크플로우

할일 기반 작업 루프

list_todos(categoryName: "OdysseyProduct", status: "notStarted")
  → 각 할일 작업 수행
  → complete_todo(todoId, completionNote)

작업 요약 → 메모

각 작업 완료 후 document/update 등에 히스토리 작성 → 요약을 메모로:

create_memo(
  title: "작업 제목",
  text: "핵심 요약...",
  categoryName: "OdysseyProduct",
  generateTimelineEvent: true
)

프로젝트 논의

list_projects()
get_project(projectId) → items[]
각 아이템은 get_todo(id) / get_memo(id)로 상세 조회

일기 / 저널

철학적 대화, 생각 정리 등을 일기 카테고리 메모로:

create_memo(
  title: "주제",
  text: "대화 요약",
  categoryName: "일기",
  generateTimelineEvent: true
)

아키텍처

MCP 클라이언트 (Claude Code/Desktop/Cursor)
    │ stdio (JSON-RPC)
    ▼
odyssey-mcp (이 패키지)
    │ HTTPS + Bearer API Key
    ▼
Firebase Functions (asia-northeast3)
    │
    ▼
Firestore (할일/메모/프로젝트/타임라인)

보안

• API Key는 sha256 해시로만 Firestore에 저장됨 (원본은 발급 시 1회만 노출)
• 모든 요청에 API Key 인증 필수
• 본인 데이터만 접근 가능
• 만료된 키는 서버에서 즉시 거부 (revokedAt 검증)
• Odyssey 앱에서 언제든 키 폐기 가능

문제 해결

첫 호출이 느리거나 응답 없음

Firebase Functions의 cold start 때문입니다. 첫 요청은 최대 10초 정도 걸릴 수 있고, 이후 호출은 즉시 응답합니다. 클라이언트 내부에서 자동 재시도(최대 3회, 누적 ~25초)가 적용되므로 그냥 기다리시면 됩니다.

"도구를 찾을 수 없음" 에러

글로벌 설치(npm i -g @odyssey365/mcp-server) 후 설정의 command를 odyssey-mcp으로 변경하세요. npx를 사용하면 npm registry 조회 시간 때문에 세션 시작 시 도구가 누락될 수 있습니다.

"API Key가 만료되었습니다"

Odyssey 앱 → 설정 → MCP 연동에서 새 키를 발급하고 odyssey-mcp install로 다시 설치하세요.

업데이트

서버가 시작될 때마다 자동으로 최신 버전을 확인하고 업데이트합니다 (다음 세션부터 적용). 자동 업데이트를 끄려면 설정 파일의 env에 "ODYSSEY_AUTO_UPDATE": "0"을 추가하거나, 설치 시 "자동 업데이트 사용?"에 N으로 답하세요. 수동 업데이트는 언제나:

odyssey-mcp update

요구사항

• Node.js 20 이상
• Odyssey 앱 계정 + API Key

라이선스

MIT