OMOS-MCP

MCP 서버로 AI 에이전트(Claude, ChatGPT, Cursor 등)가 OMOS Shared Drive에 있는 프로젝트 문서를 읽어 질문에 답변합니다. 모든 답변은 Google Drive 링크와 함께 원본 파일을 참조합니다.

지원하는 Drive 구조:

OMOS/
├── Project A/
│   ├── Project Overview/
│   ├── Timeline/
│   ├── Design/
│   │   ├── System Flow/
│   │   ├── DB/
│   │   └── API/
│   └── BRD/
└── Project B/ ...

도구

에이전트는 다음 순서로 검색합니다: 프로젝트 이름으로 필터링 → 찾을 수 없으면 프로젝트 개요를 본 후 사용자에게 확인 요청 → **타임라인 | BRD | 설계(시스템 흐름 / DB / API)**에 대한 질문인지 확인 → 질문이 너무 광범위하면 범위를 좁히기 위해 되물음 (서버 명령어에 내장되어 있음)

Related MCP server: brkt-gdrive-mcp

일회성 설정: 서비스 계정

서버는 서비스 계정으로 Drive에 접근합니다 (모든 사람이 로그인할 필요 없음):

1. console.cloud.google.com 접속 → 새 프로젝트 생성 (또는 기존 프로젝트 사용)

2. API 및 서비스 → 라이브러리 → Google Drive API 검색 → 사용 설정

3. IAM 및 관리자 → 서비스 계정 → 서비스 계정 만들기 → 이름 입력 (예: omos-mcp) → 만들기 (역할 단계는 건너뛰어도 되며, 권한을 부여할 필요 없음)

4. 생성된 서비스 계정으로 이동 → 키 탭 → 키 추가 → 새 키 만들기 → JSON → 키 파일이 다운로드됨

5. 서비스 계정 이메일(omos-mcp@<project>.iam.gserviceaccount.com 형태)을 복사하여 공유 Drive / OMOS 폴더에 이메일을 뷰어로 공유

6. OMOS 루트의 폴더 id 찾기: 브라우저에서 폴더를 열고 URL 확인 https://drive.google.com/drive/folders/<이게 id입니다>

환경 변수

로컬 실행

먼저 uv를 설치하세요 (curl -LsSf https://astral.sh/uv/install.sh | sh)

1) .env 설정 (서버가 리포지토리 루트에서 자동 로드):

cp .env.example .env

.env를 편집하여 OMOS_ROOT_FOLDER_ID와 키 파일 경로를 입력합니다 (예: 키 파일을 ./service-account.json에 배치 — gitignore에 이미 포함됨)

2) Claude Code와 연결 (stdio):

claude mcp add omos -- uv run --directory "/path/to/OMOS-MCP" omos-mcp

Claude Desktop / Cursor / Windsurf — MCP config에 추가:

{
  "mcpServers": {
    "omos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/OMOS-MCP", "omos-mcp"]
    }
  }
}

3) 테스트: 에이전트에게 "OMOS에 어떤 프로젝트가 있습니까?" 라고 물어보세요. 프로젝트 목록과 링크가 반환되어야 합니다.

(선택 사항) 로컬에서 HTTP 서버로 실행: .env에서 OMOS_AUTH_TOKEN을 활성화한 후

uv run omos-mcp-http

엔드포인트는 http://localhost:8000/mcp이며, 연결 방법:

claude mcp add --transport http omos http://localhost:8000/mcp -H "Authorization: Bearer <OMOS_AUTH_TOKEN>"

MCP 링크로 배포 (Render)

1. 이 리포지토리를 GitHub에 푸시합니다 (Dockerfile + render.yaml이 이미 포함됨)

2. Render → New → Blueprint → 이 리포지토리 선택

3. 대시보드에서 환경 변수 설정:

   • OMOS_ROOT_FOLDER_ID = OMOS 루트의 폴더 id

   • GOOGLE_SERVICE_ACCOUNT_JSON = JSON 키 파일의 전체 내용 (직접 붙여넣기)

   • OMOS_AUTH_TOKEN Render가 자동 생성 → 복사하여 팀에 공유

4. 배포 완료 → 엔드포인트는 https://<app>.onrender.com/mcp

사용자 연결:

claude mcp add --transport http omos https://<app>.onrender.com/mcp \
  -H "Authorization: Bearer <OMOS_AUTH_TOKEN>"

Cursor / VS Code: MCP config에 URL + 헤더 Authorization: Bearer <token> 추가

Claude.ai / ChatGPT (웹)에서 사용 — OAuth

웹 클라이언트는 헤더를 추가할 수 없으므로 WorkOS AuthKit와 같은 제공자를 통한 OAuth가 필요합니다 (최대 1백만 사용자 무료):

1. workos.com 가입 → AuthKit 활성화 → 로그인 방식 설정 + 팀원으로 제한

2. 대시보드 → Connect → Configuration → Client ID Metadata Document 및 Dynamic Client Registration 활성화

3. Resource Indicator 추가 = https://<app>.onrender.com (/mcp 제외)

4. Render에 환경 변수 3개 추가: OAUTH_ISSUER = AuthKit 도메인, OAUTH_AUDIENCE = https://<app>.onrender.com, PUBLIC_URL = https://<app>.onrender.com

5. 사용자: Claude.ai → Settings → Connectors → Add custom connector → https://<app>.onrender.com/mcp 입력 → WorkOS로 로그인

OAuth 모드와 bearer 토큰은 함께 사용할 수 있습니다. 웹은 OAuth를 사용하고, CLI는 여전히 토큰을 사용할 수 있습니다.

변환기 테스트

uv run python test_convert.py