gmail-mcp

다중 계정 Gmail MCP 서버로, AI 에이전트(Claude Code 및 MCP를 사용하는 모든 도구)를 위한 것입니다. 무엇보다도 하나의 설계 목표가 있습니다: 에이전트는 자유롭게 읽고 초안을 작성할 수 있지만, 모든 발송은 사람의 승인이 필요합니다.

호스팅형 Gmail 커넥터는 한 번에 하나의 계정만 묶고 제약 없이 발송하기 때문에 이 서버를 만들었습니다. 이 서버는 원하는 수의 Gmail 계정을 짧은 별칭(work, school, ...) 뒤에 묶고, 위험도에 따라 기능을 구분합니다.

서버는 의도적으로 gmail-accounts(이 아니라 gmail)로 등록됩니다. 호스팅형 Gmail 커넥터도 함께 실행하는 경우, 거의 동일한 도구 이름 때문에 에이전트가 잘못된 사서함을 읽고 확신에 찬 위음성(false negative)을 보하게 됩니다.

전송 게이트 작동 방식

1. 에이전트가 초안을 준비하고 승인을 요청합니다.

2. 사용자는 자신의 미널에서 gmail-approve를 실행하고 정확한 RFC822 페이로드를 검토한 다음, 해당 초안의 콘텐츠 해시에 바인딩된 일회용 토큰을 받습니다.

3. 에이전트는 토큰과 함께 발송 도구를 호출합니다. 잘못된 초안, 수정된 초안, 재사용된 토큰, 만료된 토큰은 모두 거부됩니다.

발송 도구에는 anthropic/reiresUserInteraction도 포함되어 있어, bypassPermissions 모드에서도 Claude Code가 사람에게 프롬프트를 웁니다. 토큰 CLI는 실수 방지 인턱록이고, 하네스 프롬프트가 강제되는 경계입니다.

Related MCP server: Gmail Multi-Inbox MCP Server

설적

Python 3.12+ 및 uv가 필요합니다.

1. Google Cloud OAuth 클라이언트

console.cloud.google.com에서 프로젝트를 만들고, Gmail API를 사용 설적하고, Desktop 앱 유형의 OAuth 클라이언트 ID를 만든 후 JSON을 다음 위적에 다운로드하세요.

~/.config/gmail-mcp/client_secret.json

2. 계정 선언

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

나중에 계정을 추가하는 것은 구성 편집과 인증 실행 한 번이면 충분합니다. 파일은 호출할 때마다 다시 읽히므로 재시작이 필요 없습니다.

3. 각 계정 인증

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

각 권한 부여는 별칭과 대조 검증됩니다. 브라우저에서 잘못된 Google 계정을 인증하면 감지되어 거부되며, 조용히 저장되지 않습니다.

4. Claude Code에 등록

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

일상적인 사용

모든 도구는 account 별칭을 받습니다. 에이전트에게 "work에서 인보이스 스레드를 검색해 줘" 또는 "personal에 답장 초안을 작섣해 줘" 같은 요청을 하세요. 발송할 때가 되면:

gmail-approve            # lists pending sends, shows the payload, mints a token

상태 확인:

uv run gmail-mcp-health

보안 참고 사항

• 비밀은 저장소에 절대 들어가지 않습니다. client_secret.json과 계정별 토큰은 ~/.config/gmail-mcp/에 위적합니다(GMAIL_MCP_CONFIG로 재정의 가능).

• 모든 구성 쓰기는 원자적입니다(tmp + fsync + rename). 쓰기 중 크래시가 발생해도 파일이 찢어지지 않습니다.

• stdout은 JSON-RPC 채널입니다. 패키지의 어떤 것도 print()를 사용할 수 없으며(ruff T201로 강제), 진단 정보가 프롬토콜을 손상시킬 수 없습니다.

테스트

uv run pytest