gmail-mcp

MCP 클라이언트용 Gmail 커넥터. 하나의 서버에서 OAuth 리프레시 토큰으로 여러 Gmail 계정을 지원합니다. 실제 MIME을 전송합니다(파일 경로 첨부, 실시간 서명, 전송 후 증빙). 모델에 수 메가바이트의 base64를 쏟아 붓지 않고 메일을 읽고 정리합니다.

Google이 호스팅하는 Gmail MCP를 감싸는 래퍼가 아닙니다 — 호스트에서 RFC822를 직접 구성하고 gmail.googleapis.com에 직접 통신합니다.

기능

• 다중 계정 OAuth — accounts_add로 사서함 추가, 토큰은 로컬에 저장(모드 0600)

• 보내기 / 답장 / 전달 — 서버가 구성한 MIME, 보낼 편지함 파일 경로만 사용, 25MB 제한, 멱등성 키, 성공 시 증빙

• 읽기 / 정리 — 검색(스레드 + 페이지네이션), 스레드/메시지 가져오기, 라벨, 보관/휴지통, 임시 보관함

• 첨부 파일 — ~/Outbox에서 전송(구성 가능), ~/Inbox로 다운로드(구성 가능)

• 이중 전송 방식 — 로컬 하네스용 stdio, 원격 클라이언트용 게이트웨이 뒤의 Streamable HTTP

Related MCP server: Gmail MCP Server

요구 사항

• Python 3.12+(개발 환경은 pyenv로 3.13 사용)

• Google Cloud 데스크톱 OAuth 클라이언트(클라이언트 ID + 시크릿)

• 포함된 LaunchAgent 스크립트(HTTP 서비스)에는 macOS 필요, Linux는 수동 실행에 사용 가능

빠른 시작

git clone https://github.com/iXanadu/gmcp.git
cd gmcp

# Python 3.12+ (example with pyenv)
pyenv virtualenv 3.13 gmail-mcp-3.13
pyenv local gmail-mcp-3.13
pip install -e '.[dev]'

# Config (see examples/)
cp examples/.env.example .env
cp examples/.keys.example .keys
chmod 600 .keys

# Sanity check
gmail-doctor

HTTP 전송을 실행하기 전에 .keys에 Google OAuth 자격 증명과 HTTP bearer 토큰을 입력하세요.

Google Cloud Console(일회성 설정)

데스크톱 OAuth 클라이언트가 필요합니다 — 서비스 계정이나 도메인 전체 위임이 아닙니다.

accounts_add를 처음 실행하면 Google에서 동의를 요청합니다. 권한 범위는 서버에 고정되어 있습니다: 메일 읽기/보내기/정리와 send-as 서명 읽기(캐시되지 않음).

사용자 이름/비밀번호, 앱 비밀번호, 또는 대화에 붙여넣는 리프레시 토큰은 없습니다.

사서함 연결(accounts_add)

accounts_add는 Google 동의를 위해 브라우저를 엽니다. stdio 전송(gmail-mcp)에서만 실행되며 HTTP에서는 실행되지 않습니다.

gmail-mcp   # stdio — required for accounts_add and accounts_remove

MCP 클라이언트에서 accounts_add를 호출하세요. 동의가 완료되면 서버는 Google이 반환한 Gmail 주소를 기록합니다. 이 주소가 다른 모든 도구의 account 키가 됩니다.

토큰은 ~/.config/gmail-mcp/tokens/에 저장됩니다(모드 0600). 필요하면 이 디렉터리를 동일한 서버를 실행하는 다른 호스트로 복사하세요.

헤드리스 서버(로컬 브라우저 없음)

OAuth 콜백은 http://127.0.0.1:8767/oauth/callback입니다. 디스플레이가 없는 머신에서도 Google 로그인 페이지를 위해 어딘가에 브라우저가 필요합니다. 일반적인 두 가지 패턴이 있습니다:

A — SSH 포트 포워딩(노트북에서 동의)

헤드리스 호스트에서 stdio MCP / accounts_add를 시작하세요. 노트북에서:

ssh -L 8767:127.0.0.1:8767 user@headless-host

서버가 출력하는 인증 URL을 여세요(또는 터널을 연결한 상태에서 MCP 클라이언트로 accounts_add를 실행하세요). 콜백은 터널을 통해 헤드리스 호스트의 127.0.0.1:8767로 전달됩니다.

B — 데스크톱에서 동의 후 토큰 복사

브라우저와 동일한 .env / .keys가 있는 Mac 또는 PC에서 accounts_add를 한 번 실행하세요. 동의 후 ~/.config/gmail-mcp/tokens/를 운영 호스트로 복사하세요(동일한 경로, 모드 0600). Google이 리프레시 토큰을 취소하지 않는 한 다시 동의할 필요가 없습니다.

배포 구성

일반적인 운영 분리 구조:

┌─────────────────────┐         ┌──────────────────────────┐
│  Operator machine   │         │  MCP server (Linux/macOS) │
│  (browser for OAuth)│         │  gmail-mcp-http           │
│  accounts_add       │  copy   │  127.0.0.1:8879           │
│  token files ───────┼────────►│  + .env / .keys           │
└─────────────────────┘  tokens └───────────┬──────────────┘
                                            │
                              Cloudflare / gateway / TLS
                                            │
                                    Hand / remote MCP client

• MCP HTTP용으로 운영자의 노트북을 공개 인터넷에 노출하지 마세요. HTTP는 서버의 루프백(127.0.0.1:8879)에 바인딩됩니다. 리버스 프록시가 TLS를 종료하고 해당 포트로 전달합니다.

• OAuth는 브라우저가 있는 곳(운영자 머신 또는 SSH 터널)에서 수행됩니다. 토큰 JSON 파일은 서버로 복사됩니다.

• 게이트웨이는 OAuth 워크스테이션이 아니라 사용자가 제어하는 서버 호스트 이름(예: mcp.example.com)을 가리킵니다.

• 긴 임의의 GMAIL_MCP_HTTP_BEARER_TOKEN을 생성하세요. 게이트웨이는 이를 Authorization: Bearer …로 제시합니다.

배포 후: gmail-doctor, ./scripts/start.sh(macOS LaunchAgent) 또는 자체 systemd 유닛을 실행한 다음 HTTP를 통해 accounts_list를 호출하여 토큰을 확인하세요.

구성

민감하지 않은 설정은 .env에, 비밀 값은 .keys에 저장합니다(값이 채워진 상태로는 둘 중 어느 것도 커밋하지 마세요). examples/.env.example 및 examples/.keys.example을 참조하세요.

구성을 변경한 후 gmail-doctor를 실행하세요.

전송 방식

stdio(로컬)

gmail-mcp

accounts_add와 accounts_remove를 포함한 모든 도구를 등록합니다.

Cursor / Claude Code MCP 구성에 venv gmail-mcp 바이너리와 cwd를 리포지토리로 설정하여 연결하세요(그래야 .env / .keys가 로드됩니다).

Streamable HTTP(게이트웨이)

gmail-mcp-http

기본적으로 127.0.0.1:8879에 바인딩됩니다. Authorization: Bearer <GMAIL_MCP_HTTP_BEARER_TOKEN>이 필요하며, 유효한 토큰이 없는 요청은 401을 받습니다.

수동 허용 목록(HTTP 전용): 읽기/정리 도구와 send, reply, forward, draft_create, draft_send, accounts_list, gmail_status. 계정 관리는 stdio에 유지됩니다.

macOS 서비스(사용자 LaunchAgent)

./scripts/start.sh    # install plist → ~/Library/LaunchAgents, load
./scripts/stop.sh
./scripts/restart.sh

체크아웃 경로나 pyenv 이름이 다르면 launchd/com.gmail-mcp.plist의 경로를 수정하세요. 로그는 logs/에 기록됩니다.

Linux에서는 동일한 루프백 바인딩으로 systemd 아래에서 gmail-mcp-http를 실행하세요 — 위의 배포 구성을 참조하세요.

도구

accounts_list, accounts_add, gmail_status를 제외한 모든 도구는 account 인자(Gmail 주소)가 필요합니다.

보내기 규칙(요약)

• 첨부 파일: { "path": "/absolute/or/under/outbox/file.pdf" } — 인라인 base64 없음

• 실제 Gmail 서명이 전송 시점에 추가됩니다(캐시되지 않음)

• 서명 뒤의 선택적 footer

• 증빙 반환: 크기, href, ok false → 도구 오류(예: 잘린 첨부 파일 또는 google.com/url 재작성)

테스트

pytest tests/ -v

모의(mocked) Gmail HTTP를 사용하며 실제 사서함이 필요하지 않습니다.

스펙

제품 요구사항: docs/specs/gmail-mcp-spec.md

라이선스

Apache-2.0