mariana-google-mcp

Claude Code가 Gmail, Google Calendar 및 Google Contacts에 안전 우선 기본값으로 액세스할 수 있도록 하는 사용자 지정 MCP(Model Context Protocol) 서버입니다.

설계 철학

이 서버는 실수로 인한 손상 위험 없이 AI가 Google 워크스페이스를 관리하도록 돕기를 원하는 사용자를 위해 구축되었습니다:

이메일 전송 불가. 초안을 작성할 수는 있지만, 전송하려면 Gmail에서 수동으로 작업해야 합니다.
삭제 불가. Gmail은 "To Be Deleted" 라벨(소프트 삭제)을 사용합니다. 캘린더는 이벤트 제목 앞에 "DELETE - "를 추가합니다. Google UI에서 검토하고 확인해야 합니다.
모든 변경 사항 기록. 추가 전용 JSONL 작업 로그가 타임스탬프, 도구 이름, 계정 및 요약과 함께 모든 쓰기 작업을 기록합니다.
다중 계정 지원. 별칭을 사용하여 개인 및 업무용 계정을 관리합니다.

설정

1. Google Cloud 프로젝트

Google Cloud Console로 이동합니다.
새 프로젝트를 만들거나 기존 프로젝트를 사용합니다.
다음 API를 활성화합니다:
- Gmail API
- Google Calendar API
- People API (연락처용)
OAuth 2.0 자격 증명을 만듭니다:
- 애플리케이션 유형: 데스크톱 앱
- 클라이언트 ID와 클라이언트 보안 비밀을 다운로드합니다.

2. 설치 및 빌드

git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install
npm run build

3. Claude Code에 추가

~/.claude.json의 mcpServers 아래에 다음을 추가합니다:

{
  "mcpServers": {
    "mariana-google-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mariana-google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

/path/to/를 실제 복제 경로로 바꾸고 OAuth 자격 증명을 입력합니다.

4. 인증

Claude Code를 다시 시작한 후 google_auth 도구를 실행합니다. OAuth 동의를 위한 브라우저 창이 열립니다. 승인되면 토큰이 로컬에 저장되고 자동으로 새로 고쳐집니다.

사용 가능한 도구 (19)

인증 및 상태

도구	설명
`google_auth`	OAuth 브라우저 흐름을 통해 Google 계정 인증
`google_status`	구성된 모든 계정의 연결 상태 확인

Gmail (9개 도구)

도구	설명
`gmail_search`	Gmail 쿼리 구문을 사용하여 메시지 검색
`gmail_read`	ID로 특정 메시지 읽기 (전체 내용)
`gmail_list_labels`	모든 Gmail 라벨/폴더 나열
`gmail_draft`	이메일 초안 작성 (전송하지 않음)
`gmail_create_label`	새 라벨 만들기 (`/`를 사용한 중첩 지원)
`gmail_apply_label`	하나 이상의 메시지에 라벨 적용
`gmail_remove_label`	하나 이상의 메시지에서 라벨 제거
`gmail_create_filter`	필터 규칙 만들기 (일치 기준 → 작업)
`gmail_move_to_delete`	소프트 삭제: 메시지를 "To Be Deleted" 라벨로 이동

캘린더 (6개 도구)

도구	설명
`calendar_list`	예정된 캘린더 이벤트 나열
`calendar_search`	키워드로 이벤트 검색
`calendar_get`	특정 이벤트의 전체 세부 정보 가져오기
`calendar_create`	이벤트 만들기 (기본적으로 초대장을 보내지 않음)
`calendar_update`	기존 이벤트 수정 (기본적으로 참석자에게 알리지 않음)
`calendar_flag_delete`	소프트 삭제: 이벤트 제목 앞에 "DELETE - " 추가
`calendar_availability`	날짜 범위에 대한 여유/바쁨 상태 확인

연락처 (2개 도구)

도구	설명
`contacts_search`	이름, 이메일 또는 전화번호로 연락처 검색
`contacts_list`	그룹별로 필터링하여 연락처 나열

다중 계정 지원

친숙한 이름을 사용하여 여러 Google 계정을 인증할 수 있습니다:

google_auth account_name: "primary"
google_auth account_name: "newsletters"
google_auth account_name: "work"

대부분의 도구는 선택적 account 매개변수를 허용합니다. 생략하면 기본 계정이 사용됩니다. google_status를 사용하여 구성된 모든 계정과 해당 상태를 확인하세요.

구성 파일

모든 구성은 ~/.config/mariana-google-mcp/에 저장됩니다:

파일	목적
`config.json`	계정 레지스트리 (이름, 이메일 해시, 기본값)
`tokens/<hash>.json`	계정별 OAuth 토큰 (자동 새로 고침)
`actions.jsonl`	모든 변경 사항의 추가 전용 로그

토큰은 일반 텍스트 이메일이 아닌 이메일 해시로 저장되어 간접적인 계층을 제공합니다.

작업 로그

모든 쓰기 작업(초안, 캘린더 생성/업데이트, 소프트 삭제)은 다음 형식으로 ~/.config/mariana-google-mcp/actions.jsonl에 기록됩니다:

{"timestamp":"2026-04-03T10:30:00.000Z","tool":"gmail_draft","account":"primary","summary":"Draft created: subject='Meeting follow-up'"}

로그는 추가 전용이며 서버에 의해 수정되지 않습니다. 언제든지 검토하여 Claude가 수행한 작업을 감사할 수 있습니다.

포크 및 사용

자신의 Google 계정으로 이를 사용하려면:

이 저장소를 포크합니다.
자신만의 Google Cloud 프로젝트와 OAuth 자격 증명을 만듭니다 (위의 설정 참조).
Claude Code 구성을 포크의 dist/index.js를 가리키도록 빌드하고 설정합니다.
google_auth를 실행하여 인증합니다.

코드 변경이 필요하지 않습니다. 모든 계정별 데이터는 구성 파일과 환경 변수에 저장됩니다.

기술 스택

TypeScript
@modelcontextprotocol/sdk — MCP 프로토콜 구현
googleapis — Google API 클라이언트
google-auth-library — OAuth2 토큰 관리
zod — 입력 유효성 검사

라이선스

MIT

Mariana Google MCP