Gmail MCP 서버

Gmail에 대한 읽기 전용 액세스를 제공하는 MCP(Model Context Protocol) 서버입니다. Claude Code가 안전하게 Gmail 받은 편지함을 검색, 읽기 및 분석할 수 있도록 합니다.

기능

• search_emails - Gmail 쿼리 구문을 사용하여 검색

• list_unread - 읽지 않은 이메일 목록 확인

• get_message - 첨부 파일 메타데이터를 포함한 전체 메시지 내용 가져오기

• get_thread - 대화 스레드의 모든 메시지 가져오기

• draft_reply - 답장 초안 내용 준비 (전송하지 않음)

Related MCP server: Gmail MCP Server

사전 요구 사항

• Node.js 18 이상

• Gmail API가 활성화된 Google Cloud 프로젝트

• OAuth 2.0 데스크톱 앱 자격 증명

Google Cloud 설정

1. Google Cloud 프로젝트 생성

1. Google Cloud 콘솔로 이동합니다.

2. "프로젝트 선택" → "새 프로젝트"를 클릭합니다.

3. 프로젝트 이름을 지정합니다 (예: "Gmail MCP Server").

4. "만들기"를 클릭합니다.

2. Gmail API 활성화

1. 프로젝트에서 "API 및 서비스" → "라이브러리"로 이동합니다.

2. "Gmail API"를 검색합니다.

3. 해당 항목을 클릭하고 "사용"을 누릅니다.

3. OAuth 동의 화면 구성

1. "API 및 서비스" → "OAuth 동의 화면"으로 이동합니다.

2. "외부"(또는 Google Workspace를 사용하는 경우 "내부")를 선택합니다.

3. 필수 필드를 입력합니다:

   • 앱 이름: "Gmail MCP Server"

   • 사용자 지원 이메일: 본인 이메일

   • 개발자 연락처: 본인 이메일

4. "저장 후 계속"을 클릭합니다.

5. 범위를 추가합니다:

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

6. 테스트 사용자로 본인 이메일을 추가합니다 (외부인 경우).

7. 설정을 완료합니다.

4. OAuth 자격 증명 생성

1. "API 및 서비스" → "사용자 인증 정보"로 이동합니다.

2. "사용자 인증 정보 만들기" → "OAuth 클라이언트 ID"를 클릭합니다.

3. 애플리케이션 유형으로 "데스크톱 앱"을 선택합니다.

4. 이름을 지정합니다 (예: "Gmail MCP Desktop").

5. "만들기"를 클릭합니다.

6. 클라이언트 ID와 클라이언트 보안 비밀번호를 다운로드하거나 복사합니다.

설치

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

구성

1. 예제 환경 파일을 복사합니다:

cp .env.example .env

2. OAuth 자격 증명으로 .env를 편집합니다:

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

첫 실행 (인증)

서버를 처음 실행하면 다음 작업이 수행됩니다:

1. Google 인증을 위해 브라우저를 엽니다.

2. 로그인 및 권한 부여를 요청합니다.

3. 토큰을 token.json에 로컬로 저장합니다.

이후 실행 시에는 저장된 토큰을 자동으로 재사용합니다.

Claude Code와 함께 사용하기

MCP 서버 추가

claude mcp add gmail node ./dist/index.js

또는 Claude Code 구성에 수동으로 추가합니다:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

사용 가능한 도구

search_emails

Gmail 쿼리 구문을 사용하여 이메일을 검색합니다.

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

읽지 않은 이메일 목록을 확인합니다 (is:unread 검색의 바로가기).

get_message

메시지 ID로 특정 이메일의 전체 내용을 가져옵니다.

get_thread

스레드 ID로 대화 스레드의 모든 메시지를 가져옵니다.

draft_reply

스레드에 대한 답장 초안을 준비합니다. 응답 작성을 위한 컨텍스트를 제공하지만 이메일을 전송하지는 않습니다.

개발

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

보안 참고 사항

• OAuth 토큰은 token.json에 로컬로 저장됩니다.

• .env 또는 token.json을 버전 관리 시스템에 커밋하지 마십시오.

• 서버는 읽기 및 작성 권한만 요청합니다.

• 이메일은 전송되지 않습니다 - draft_reply는 내용만 준비합니다.

• 이메일 내용은 로그에 기록되지 않습니다.

문제 해결

"Missing CLIENT_ID or CLIENT_SECRET"

.env 파일이 존재하고 유효한 자격 증명이 포함되어 있는지 확인하십시오.

"Authorization timeout"

OAuth 흐름에는 5분의 제한 시간이 있습니다. 서버를 다시 시작하고 즉시 인증을 완료하십시오.

"Token refresh failed"

token.json을 삭제하고 다시 인증하십시오.

"Access blocked: This app's request is invalid"

OAuth 동의 화면이 올바르게 구성되었는지, 그리고 본인 이메일이 테스트 사용자로 추가되었는지 확인하십시오.