클라이언트	설정 파일	최상위 키	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 구조로 자동 기록합니다.

웹 AI (Claude.ai / ChatGPT / Notion 등)

이 npm 패키지는 내 컴퓨터에서 실행하는 stdio 클라이언트용입니다. 설치 없이 웹 AI에서 바로 쓰려면 호스티드 리모트 커넥터를 사용하세요 — 동일한 도구를 OAuth로 노출합니다.

엔드포인트: https://mcp-odyssey30-60.odyssey365.app
OAuth 2.1 + DCR 지원 (Claude.ai 커스텀 커넥터 등은 이 URL만 추가하면 로그인 창으로 연결).
API Key 헤더를 지원하는 클라이언트는 앱에서 외부 AI(remote) 키를 발급받아 Authorization: Bearer <키> 로 설정.

앱 → 설정 → MCP 연동에서 용도에 맞는 키(내 디바이스 / 외부 AI)를 발급합니다.

빠른 시작

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 (26개)

할일

list_todos — 카테고리·상태·오늘/전체·태그 필터 조회 (정렬·페이지네이션)
get_todo — 상세 조회 (체크리스트/달성조건 포함)
create_todo — 할일 생성 (done 상태·사후기록·deadline 지원)
update_todo — 할일 수정 (deadline 교체/해제)
delete_todo — 할일 삭제
complete_todo — 완료 처리 (타임라인 이벤트 자동 생성)

메모 / 일기

list_memos — 메모 목록 (본문 미리보기, 임베드 assetCount)
get_memo — 메모 상세 (plain text 변환 + 임베드 이미지/비디오 URL을 assets[]로 노출)
read_memo_image — 메모 임베드 이미지를 다운스케일해 image content로 반환 (비전 입력용)
create_memo — 메모 생성 (plain text → Quill Delta 자동 변환, 타임라인 이벤트 자동 생성)
delete_memo — 메모 삭제

캘린더

list_events — 기간 내 캘린더 이벤트 조회
get_event — 단일 이벤트 상세
create_event — 캘린더 이벤트 생성

타임라인 (수행·회고 기록)

create_timeline_event — 타임라인 이벤트 생성 (대화를 수행/회고로 묶기, reflectionElements 지원)
add_item_to_timeline_event — 기존 타임라인 이벤트에 아이템 첨부

프로젝트

list_projects — 프로젝트 목록 (정렬·페이지네이션)
get_project — 상세 + 포함 아이템(items[]) 평탄화 (includeComponents로 보드 원본 포함)
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' | 'remove'
delete_project_component — 컴포넌트 제거 (참조 links 함께 정리)

설정

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

도구는 백엔드 SSOT(functions_v2/src/mcp/tools/*.ts) 한 곳에서 관리되며, 이 npm 패키지는 stdio→리모트 프록시입니다. 도구 추가/변경은 백엔드 배포만으로 반영되고 npm 재배포는 불필요합니다.

주요 워크플로우

할일 기반 작업 루프

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

Keywords

mcp

model-context-protocol

FAQs

What is @odyssey365/mcp-server?

Is @odyssey365/mcp-server well maintained?

Package last updated on 09 Jul 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@odyssey365/mcp-server