Gmail MCP 서버 구성

Gmail은 AI 에이전트가 Gmail 데이터와 안전하게 상호작용할 수 있는 원격 모델 컨텍스트 프로토콜 (MCP) 서버를 제공합니다. Gmail MCP 서버를 구성하면 Google Antigravity 및 Claude와 같은 AI 애플리케이션이 Gmail에서 작업을 실행할 수 있습니다.

Gmail MCP 서버는 AI 에이전트가 다음 작업을 수행할 수 있는 표준화된 방법을 제공합니다.

  • 데이터 읽기: 이메일을 검색하고, 스레드를 가져오고, 라벨을 나열합니다.
  • 실행: 이메일 초안을 만들고 메시지에 라벨을 지정합니다.
  • 보안 준수: 사용자와 동일한 권한 및 데이터 거버넌스 컨트롤을 상속합니다.

기본 요건

Gmail MCP 서버 구성

Gmail MCP 서버를 사용하려면 Google Cloud 프로젝트에서 사용 설정한 다음 MCP 클라이언트가 연결되도록 구성해야 합니다.

API 사용 설정

Gmail MCP 서버를 사용하려면 Google Cloud 프로젝트에서 다음 API를 사용 설정해야 합니다.

  • Gmail API

CLI

gcloud services enable gmail.googleapis.com --project=PROJECT_ID

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

콘솔

Google Cloud 콘솔에서 API를 사용 설정합니다.

API 사용 설정

MCP 서비스 사용 설정

Gmail용 MCP 구성요소를 사용 설정하려면 Google Cloud 프로젝트에서 다음 서비스를 사용 설정해야 합니다.

  • Gmail MCP API

CLI

gcloud services enable gmailmcp.googleapis.com --project=PROJECT_ID

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

콘솔

Google Cloud 콘솔에서 MCP 서비스를 사용 설정합니다.

MCP 서비스 사용 설정

Gmail MCP 서버는 인증 및 승인에 OAuth 2.0을 사용합니다. OAuth 클라이언트 ID를 만들려면 먼저 OAuth 동의 화면을 구성해야 합니다.

  1. Google Cloud 콘솔에서 Google 인증 플랫폼 > 브랜딩으로 이동합니다.

    브랜딩으로 이동

  2. 이미 Google 인증 플랫폼을 구성한 경우 브랜딩, 대상, 데이터 액세스에서 다음 OAuth 동의 화면 설정을 구성할 수 있습니다. Google 인증 플랫폼이 아직 구성되지 않음이라는 메시지가 표시되면 시작하기를 클릭합니다.

    1. 앱 정보의 앱 이름에 Gmail MCP Server를 입력합니다.
    2. 사용자 지원 이메일에서 이메일 주소 또는 적절한 Google 그룹을 선택합니다.
    3. 다음을 클릭합니다.
    4. 대상에서 내부를 선택합니다. 내부를 선택할 수 없는 경우 외부를 선택합니다.
    5. 다음을 클릭합니다.
    6. 연락처 정보에서 프로젝트 변경사항에 대한 알림을 받을 수 있는 이메일 주소를 입력합니다.
    7. 다음을 클릭합니다.
    8. 완료에서 Google API 서비스 사용자 데이터 정책을 검토하고 동의하는 경우 Google API 서비스: 사용자 데이터 정책에 동의합니다를 선택합니다.
    9. 계속을 클릭합니다.
    10. 만들기를 클릭합니다.
    11. 사용자 유형으로 외부를 선택한 경우 테스트 사용자를 추가합니다.
      1. 잠재고객을 클릭합니다.
      2. 테스트 사용자에서 사용자 추가를 클릭합니다.
      3. 이메일 주소와 기타 승인된 테스트 사용자를 입력한 후 저장을 클릭합니다.

  3. 데이터 액세스 > 범위 추가 또는 삭제를 클릭합니다. Google Cloud 프로젝트에서 사용 설정한 각 API의 범위 목록이 패널에 표시됩니다.

    1. 직접 범위 추가에서 Gmail MCP 서버의 범위를 붙여넣습니다.

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

    2. 표에 추가를 클릭합니다.

    3. 업데이트를 클릭합니다.

    4. 앱에 필요한 범위를 선택한 후 데이터 액세스 페이지에서 저장을 클릭합니다.

MCP 클라이언트 구성

Gmail 원격 MCP 서버를 MCP 클라이언트에 추가하려면 클라이언트의 안내를 따르세요.

Antigravity

Gmail 원격 MCP 서버를 Antigravity에 추가하려면 mcp_config.json 파일에 서버 구성을 추가하세요. 이 안내는 Antigravity 2.0, Antigravity IDE, Antigravity CLI를 지원합니다.

  1. OAuth 2.0 클라이언트 ID 및 보안 비밀을 만듭니다.

    1. Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기로 이동합니다.

      클라이언트 만들기로 이동

    2. 애플리케이션 유형으로 웹 애플리케이션을 선택합니다.

    3. 이름을 입력합니다.

    4. 승인된 리디렉션 URI 섹션에서 + URI 추가를 클릭한 다음 URI 필드에 https://antigravity.google/oauth-callback를 추가합니다.

    5. 만들기를 클릭하고 클라이언트 ID와 클라이언트 보안 비밀번호를 복사합니다.

  2. 구성 파일 ~/.gemini/antigravity/mcp_config.json을 열거나 만듭니다.

  3. mcpServers 구성을 mcp_config.json에 추가합니다.

    {
  "mcpServers": {
    "gmail": {
      "serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

    다음을 바꿉니다.

    • OAUTH_CLIENT_ID: 생성한 클라이언트 ID입니다.
    • OAUTH_CLIENT_SECRET: 생성한 클라이언트 보안 비밀번호입니다.

  4. mcp_config.json 할인을 받으세요.

  5. MCP 서버를 인증합니다. GUI 설정 또는 CLI를 사용하여 인증할 수 있습니다.

    • Antigravity IDE 또는 GUI (Antigravity 2.0)의 경우:

      1. 설정 화면을 엽니다 (예: 왼쪽 하단에서 설정을 클릭하거나 Antigravity 사용자 설정을 엽니다).
      2. 맞춤설정으로 이동합니다.
      3. 설치된 MCP 서버에서 새로고침을 클릭합니다.
      4. 목록에서 gmail를 찾아 인증을 클릭하고 Google 계정에 로그인한 후 승인 코드를 복사하여 입력 대화상자에 붙여넣고 제출을 클릭합니다.

    • Antigravity CLI:

      1. Antigravity CLI를 시작합니다.

        agy

      2. 다음을 실행하여 대화형 MCP 관리 패널을 엽니다.

        /mcp

      3. 화살표 키를 사용하여 gmail를 선택하고 인증 작업으로 이동한 후 Enter를 누릅니다. 브라우저에서 로그인 흐름을 완료하고 승인 코드를 복사하여 터미널 프롬프트에 붙여넣은 후 Enter를 누릅니다.

  6. 서버가 올바르게 구성되어 있고 실행 중인지 확인합니다.

    • Antigravity IDE 또는 GUI: 맞춤설정 > 설치된 MCP 서버 아래 서버 옆에 로그아웃 버튼이 표시됩니다.
    • Antigravity CLI: /mcp 패널을 열어 구성된 MCP 서버를 확인합니다. 인증된 서버는 대화형 TUI 패널 내 이름 옆에 Authed가 표시됩니다. 대시보드 뷰에서 서버를 선택하여 상태를 검사하고 사용 가능한 모든 도구를 나열할 수 있습니다.

원격 MCP 서버를 Antigravity에서 사용할 수 있습니다.

Claude

Claude.ai 또는 Claude 데스크톱에서 Gmail 원격 MCP 서버를 사용하려면 Claude Enterprise, Pro, Max 또는 Team 요금제가 있어야 합니다.

Gmail 원격 MCP 서버를 Claude에 추가하려면 OAuth 클라이언트 ID와 보안 비밀번호를 사용하여 맞춤 커넥터를 구성하세요.

  1. OAuth 2.0 클라이언트 ID 및 보안 비밀을 만듭니다.

    1. Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기로 이동합니다.

      클라이언트 만들기로 이동

    2. 애플리케이션 유형으로 웹 애플리케이션을 선택합니다.

    3. 이름을 입력합니다.

    4. 승인된 리디렉션 URI 섹션에서 + URI 추가를 클릭한 다음 URI 필드에 https://claude.ai/api/mcp/auth_callback를 추가합니다.

    5. 만들기를 클릭하고 클라이언트 ID와 클라이언트 보안 비밀번호를 복사합니다.

  2. Claude에서 MCP 서버를 구성합니다.

    1. Claude.ai 또는 Claude Desktop에서 설정 (또는 관리 설정) > 커넥터로 이동합니다.
    2. 맞춤 커넥터 추가를 클릭합니다.
    3. Gmail 제품의 연결 세부정보를 입력합니다.
      • 서버 이름: Gmail.
      • 원격 MCP 서버 URL: https://gmailmcp.googleapis.com/mcp/v1
    4. 고급 설정에서 OAuth 클라이언트 ID 및 OAuth 클라이언트 보안 비밀번호를 입력합니다.
    5. 추가를 클릭합니다.

기타

많은 AI 애플리케이션에는 원격 MCP 서버에 연결하는 방법이 있습니다. 일반적으로 서버 이름, 엔드포인트, 전송 프로토콜, 인증 방법과 같은 서버에 관한 세부정보를 입력해야 합니다. Gmail 원격 MCP 서버의 경우 다음을 입력합니다.

  • 서버 이름: gmail

  • 서버 URL: https://gmailmcp.googleapis.com/mcp/v1

  • 전송: HTTP

  • 인증: Gmail 원격 MCP 서버는 OAuth 2.0을 사용합니다. 자세한 내용은 인증 및 승인 알아보기를 참고하세요.

다양한 유형의 클라이언트 연결에 대한 자세한 내용은 AI 애플리케이션에서 MCP 구성을 참고하세요.

Gmail MCP 서버 테스트

MCP 클라이언트를 구성한 후 테스트 프롬프트를 실행하여 연결을 확인할 수 있습니다.

MCP 클라이언트에게 다음과 같이 질문해 보세요.

  • "아리엘이 마지막 이메일에서 마케팅 계획에 대해 뭐라고 말했지?"

    클라이언트는 gmail.search_threads를 사용하여 Ariel의 이메일을 필터링하고, gmail.get_thread로 최신 대화목록의 콘텐츠를 가져온 다음, 이를 요약합니다.

  • 'ariel@example.com에게 마케팅 계획을 승인한다는 이메일을 작성해 줘.'

    클라이언트는 gmail.create_draft를 사용하여 초안 폴더에 이메일을 만들어 사용자가 Gmail에서 검토하고 보낼 수 있도록 합니다.

도구가 성공적으로 실행되고 관련 응답이 수신되면 Gmail MCP 서버가 올바르게 구성된 것입니다.

문제 해결

MCP 서버에 연결하는 데 문제가 발생하면 OAuth 로그에서 오류를 확인할 수 있습니다. 관리자에게 보안 조사 도구에서 OAuth 로그 이벤트를 확인해 달라고 요청하세요.

도구 참조

Gmail MCP 서버에는 다음 도구를 사용할 수 있습니다.

  • create_draft
  • get_thread
  • label_message
  • label_thread
  • list_drafts
  • list_labels
  • search_threads
  • unlabel_message
  • unlabel_thread

중요한 보안 고려사항: 간접 프롬프트 인젝션

언어 모델을 신뢰할 수 없는 데이터에 노출하면 간접 프롬프트 삽입 공격의 위험이 있습니다. Google Antigravity와 같은 MCP 클라이언트는 Gmail MCP 서버를 통해 강력한 도구와 API에 액세스할 수 있으므로 Google 계정의 데이터를 읽고 수정하고 삭제할 수 있습니다.

이러한 위험을 완화하려면 다음 권장사항을 따르세요.

  • 신뢰할 수 있는 도구만 사용하세요. 신뢰할 수 없거나 인증되지 않은 애플리케이션에 Gmail MCP 서버를 연결하지 마세요.
  • 신뢰할 수 없는 입력에 주의하세요. MCP 클라이언트가 확인되지 않은 소스의 이메일이나 기타 리소스를 처리하도록 요청하지 마세요. 이러한 입력에는 세션을 가로채 공격자가 데이터를 수정, 도용 또는 삭제할 수 있도록 하는 숨겨진 명령어가 포함될 수 있습니다.
  • 모든 작업을 검토합니다. AI 클라이언트가 사용자를 대신하여 취한 조치가 올바르고 사용자의 의도와 일치하는지 항상 주의 깊게 검토하세요.