gmail-read-mcp

단일 사서함으로 범위가 제한된 읽기 전용 Gmail MCP 서버입니다. stdio를 통해 두 가지 도구를 노출합니다:

• list_emails - 날짜 범위 내에서 수신된 이메일 목록: 메타데이터 + 스니펫, 오래된 것부터 (최대 500개)

• read_email - ID로 이메일 하나의 전체 헤더와 본문 텍스트 읽기

쓰기, 보내기, 라벨, 삭제 기능은 없습니다. 모든 결과에는 사서함에 로그인한 모든 사람이 이메일을 열 수 있는 jump_url 딥 링크(rfc822msgid: 검색)가 포함됩니다. 사서함 자체에서 보낸 메일(팀의 답장)은 기본적으로 제외되며, 스팸과 휴지통은 항상 제외됩니다.

Google OAuth 설정

1. Google Cloud 프로젝트를 생성하고(프로덕션 프로젝트와 분리 — 동의 화면은 프로젝트별로 적용됨) Gmail API를 활성화합니다.

2. OAuth 동의 화면을 내부로 설정합니다(gmail.readonly 범위에 대한 제한된 범위 검증을 건너뜁니다).

3. 데스크톱 앱 유형의 OAuth 클라이언트를 만들고 클라이언트 JSON을 다운로드합니다.

4. 대상 사서함으로 로그인한 상태에서 일회성 동의 흐름을 실행합니다:

   node scripts/gmail-oauth-once.mjs <path-to-client-secret.json>

   리프레시 토큰과 바인딩된 사서함을 출력합니다.

리프레시 토큰은 만료되지 않지만, Google은 계정 비밀번호가 변경되면 Gmail 범위 토큰을 취소합니다. 서버가 invalid_grant로 실패하기 시작하면 4단계를 다시 실행하고 GMAIL_REFRESH_TOKEN을 교체하세요.

Related MCP server: Gmail MCP Server

로컬 설정

cp .env.example .env
# Fill in GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN
npm install
npm start

테스트

npm test