Gmail MCP 서버

Gmail MCP 서버는 Node.js/TypeScript 기반의 MCP stdio 서버로, OpenClaw가 Model Context Protocol을 통해 Gmail 이메일을 읽을 수 있도록 합니다.

기능

Gmail API OAuth 2.0 인증 사용, 읽기 전용 권한 범위: https://www.googleapis.com/auth/gmail.readonly
list_emails: 받은 편지함 이메일 목록 조회, maxResults 및 Gmail query 필터링 지원
get_email: messageId를 통해 단일 이메일 상세 내용 읽기
search_emails: Gmail 검색 구문을 통한 이메일 검색
list_labels: 모든 Gmail 라벨/폴더 목록 조회
MCP stdio transport 지원, OpenClaw에서 호출 가능

환경 요구 사항

Node.js 18 이상
npm
Gmail API에 액세스할 수 있는 Google 계정

설치

npm install
npm run build

Google Cloud Console에서 OAuth 자격 증명 생성

Google Cloud Console을 엽니다.
프로젝트를 생성하거나 선택합니다.
APIs & Services -> Library로 이동하여 Gmail API를 검색하고 활성화합니다.
APIs & Services -> OAuth consent screen으로 이동합니다.
사용자 유형을 선택합니다. 개인용은 보통 External을 선택합니다.
앱 이름, 사용자 지원 이메일, 개발자 연락처 이메일을 입력합니다.
Scopes 단계에서 Gmail 읽기 전용 권한을 추가합니다: https://www.googleapis.com/auth/gmail.readonly.
앱이 Testing 상태인 경우, Test users에 본인의 Gmail 계정을 추가합니다.
APIs & Services -> Credentials로 이동합니다.
Create Credentials -> OAuth client ID를 클릭합니다.
Application type으로 Desktop app을 선택합니다.
생성 후 JSON 파일을 다운로드합니다.

credentials.json 배치

구성 디렉토리를 생성하고 다운로드한 OAuth JSON을 다음 경로에 저장합니다:

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

최종 경로는 다음과 같아야 합니다:

~/.gmail-mcp/credentials.json

인증 프로세스 실행

npm run auth

스크립트 수행 작업:

임시 로컬 OAuth 콜백 서비스 시작
브라우저를 열어 Google 인증 진행
인증 완료 후 토큰을 ~/.gmail-mcp/token.json에 저장

브라우저가 자동으로 열리지 않으면 터미널에 출력된 인증 URL을 복사하여 브라우저에 붙여넣으세요.

MCP 서버 시작

npm run start

start는 stdio transport를 사용하며, 일반적으로 OpenClaw가 MCP 서버 하위 프로세스로 시작하므로 수동으로 계속 실행할 필요가 없습니다.

OpenClaw MCP 구성 예시

명령어를 본 프로젝트 빌드 후의 진입점으로 지정합니다:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
    }
  }
}

프로젝트 디렉토리 내에서 npm으로 시작할 수도 있습니다:

{
  "mcpServers": {
    "gmail": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/Volumes/DevDisk/symbol/gmailMCP"
    }
  }
}

Tools 매개변수 설명

list_emails

받은 편지함 이메일 목록을 조회합니다.

{
  "maxResults": 10,
  "query": "from:example@gmail.com newer_than:7d"
}

maxResults: 선택 사항, 기본값 10, 최대 50
query: 선택 사항, Gmail 검색 구문, INBOX 내 검색으로 제한됨

get_email

단일 이메일 상세 내용을 읽습니다.

{
  "messageId": "18f..."
}

반환 필드에는 발신자, 수신자, 제목, 날짜, 라벨, 본문 텍스트, HTML 본문 및 첨부 파일 메타데이터가 포함됩니다.

search_emails

Gmail 이메일을 검색합니다.

{
  "query": "subject:invoice has:attachment newer_than:30d",
  "maxResults": 10
}

query: 필수, Gmail 검색 구문 지원
maxResults: 선택 사항, 기본값 10, 최대 50

list_labels

모든 라벨/폴더 목록을 조회합니다.

{}

파일 위치

OAuth 자격 증명: ~/.gmail-mcp/credentials.json
OAuth 토큰: ~/.gmail-mcp/token.json
MCP 서버 진입점: dist/src/index.js

자주 묻는 질문

Missing Gmail OAuth credentials

Google OAuth 클라이언트 JSON을 다운로드했는지 확인하고 다음 경로에 저장했는지 확인하세요:

~/.gmail-mcp/credentials.json

Missing Gmail OAuth token

먼저 다음을 실행하세요:

npm run auth

access_denied 또는 앱 미검증

OAuth consent screen이 여전히 Testing 상태라면, 현재 Gmail 계정을 Test users에 추가해야 합니다.

invalid_grant

기존 토큰을 삭제한 후 다시 인증하세요:

rm ~/.gmail-mcp/token.json
npm run auth

gmail-mcp