수신함, 방치하고 있지는 않은가. 업무 연락, 서비스로부터의 알림, 확인해야 할 공지사항. 하나하나의 양은 그리 많지 않은데, 쌓이다 보면 "그 건, 어떤 메일이었더라"라고 찾는 것만으로도 은근히 시간을 잡아먹는다.

나는 최근, Claude Code에게 다른 작업들을 점점 더 많이 맡길 수 있게 되었다. 코드를 작성하고, 명령어를 입력하고, 브라우저를 조작한다(이것은 지난번에 작성한 "Claude Code에게 브라우저를 조작하게 해보았다 ── GitHub Copilot이 할 수 있다면 어떨까 싶어 Playwright MCP를 추가한 이야기"의 이야기). 그런데 메일만큼은 결국 항상 직접 열어서, 내 눈으로 읽으러 가고 있었다. "이것도 Claude Code에게 맡길 수 없는 걸까"라고 생각한 것이 이번의 출발점.

조사해 보니, Claude Code에 기능을 추가하는 방법은 "내 PC에 서버를 세우는 것"뿐만이 아니었다. claude.ai 측에서 계정 연동을 하나 연결하는 것만으로 가능한 경로가 있다. 이번에는 그것을, 누구나 알고 있는 Gmail로 시도해 본다.

본 기사는 "메일 내용을 어떻게 활용했는가"가 아니라, "기능을 어떻게 늘렸는가"에 대한 절차 기사이다. 동작 확인에는 서비스로부터 도착하는 자동 발신 메일(Qiita의 주간 서머리)만을 사용하였으며, 계정명·이메일 주소·본문에 등장하는 다른 사용자의 ID는 숨겼다. 절차의 세부 사항은 공식 문서에서 확인한 내용으로 한정했다.

Claude Code 입장에서 본 "기능을 늘리는 방법"을 도식화하면 다음과 같다.

지난번에는 브라우저를 조작하게 하는 Playwright MCP를 로컬에 추가하는 이야기를 썼다. 그것은 로컬 MCP 서버의 루트로, 명령어 한 줄로 내 PC 안에 서버가 세워지는 가장 이해하기 쉬운 형태다. 이번에는 또 다른 방식인, 내 PC에는 아무것도 세우지 않고 기능을 늘리는 이야기가 된다.

지난번과는 대조적으로, npx도 추가 명령어도 필요 없다. 준비할 것은 실질적으로 "로그인 방식"과 "Google 계정" 두 가지뿐이다.

claude.ai 측에서 계정 연동을 연결한 후, Claude Code 측에서 읽어 들인다. 이 2단계 흐름을 순서대로 살펴보자.

이 부분이 가장 놓치기 쉽다. claude.ai의 커넥터(Connector)는, Claude Code가 claude.ai의 구독 계정으로 로그인되어 있을 때만 보인다. 공식 문서에 다음과 같이 명시되어 있다.

Connectors from claude.ai are fetched only when your active authentication method is a claude.ai subscription login. They aren't loaded when

ANTHROPIC_API_KEY,
ANTHROPIC_AUTH_TOKEN,
apiKeyHelper,

or a third-party provider such as Amazon Bedrock or Google Cloud's Agent Platform is active, even if you previously ran /login.

(claude.ai의 커넥터는 인증 방식이 claude.ai의 구독 로그인으로 되어 있을 때만 가져온다. ANTHROPIC_API_KEY · ANTHROPIC_AUTH_TOKEN · apiKeyHelper, 혹은 Amazon Bedrock이나 Google Cloud의 Agent Platform과 같은 서드파티(Third-party)를 통한 인증이 활성화된 경우에는, 이전에 /login을 실행했더라도 로드되지 않는다.)

현재의 로그인 방식은 다음 명령어로 확인할 수 있다.

/status

구독 계정으로 로그인되어 있지 않다면 /login으로 다시 로그인한다. 이 부분이 갖춰져 있지 않으면 이후의 절차를 모두 수행하더라도 커넥터가 보이지 않은 채로 남게 되므로, 가장 먼저 확인해 둔다.

이 부분이 이번에 가장 중요한 단계다──주역(Gmail 커넥터)의 설치 및 연결은 Claude Code 내부가 아니라 claude.ai의 브라우저 화면에서 수행한다. 이유는 인증 메커니즘에 있다. 공식 문서에는 다음과 같이 적혀 있다.

Some Anthropic-hosted connectors, such as Microsoft 365, Gmail, and Google Calendar, don't support local OAuth from Claude Code because the upstream identity provider only accepts the redirect URL that claude.ai registered.

(Microsoft 365, Gmail, Google Calendar 등의 일부 커넥터는 Google 측과 같은 인증 제공자(Identity Provider)가 claude.ai가 등록한 리다이렉트 URL(Redirect URL)만을 허용하기 때문에, Claude Code에서 직접 OAuth를 수행할 수 없다)

즉, "Claude Code 내부에서만 완결되는 연결 방법"이 애초에 마련되어 있지 않다. claude.ai 측에서 인증을 마친 뒤, 그 결과를 Claude Code가 빌려 쓰는 설계로 되어 있다. 실제 절차는 다음과 같다 (출처: 상동, Anthropic 지원 문서 "Use Google Workspace connectors").

• 브라우저에서 claude.ai/customize/connectors 를 연다 (설정 내의 "Customize > Connectors"를 통해서도 접근 가능하다)
• 목록에서 Gmail을 선택하고, "Connect" 또는 "Install"을 눌러 Google 계정으로 OAuth 인증을 진행한다
• 인증 프롬프트의 지시에 따라 요구되는 권한을 확인한 후 허가한다

인가(Authorization) 화면에 나타나는 권한에 대해서는 후술한다.

이 시점에서, Claude Code의 설정 파일에는 아무것도 기록되지 않는다. 연결 정보는 claude.ai의 계정 측에 저장된다. 지난번 Playwright MCP 때처럼 claude mcp add 명령어를 입력해야 하는 상황은 한 번도 나오지 않는다.

claude.ai 측의 연결이 끝났다면, Claude Code로 돌아와 확인한다.

/mcp

목록에 claude.ai 유래의 서버로서 Gmail이 나타나면 성공이다. 만약 나타나지 않는다면, /status로 인증 방식을 확인하고, 해당 환경 변수나 apiKeyHelper 설정을 해제한 뒤 /login으로 claude.ai 계정을 다시 선택하면 된다 (출처: 상동).

연결되었다면, 이제 일본어(또는 한국어)로 부탁하기만 하면 된다. 실제로 이렇게 부탁해 보았다.

Qiita에서 온 메일을 최근 60일 이내 데이터에서 찾아줘.

이때 백그라운드에서 실행된 호출은 다음과 같았다.

mcp__claude_ai_Gmail__search_threads
query: "from:noreply@qiita.com newer_than:60d"
pageSize: 5

이 부분이 개인적으로 가장 흥미로웠던 지점인데, "Qiita에서 온 메일", "최근 60일"이라는 자연어가 from:과 newer_than:이라는 Gmail의 검색 구문(Search Syntax)으로 변환되어 실행되고 있다. Gmail 검색창에 직접 입력하는 것과 동일한 문법이다. 평소에 이 구문을 외우고 있지 않더라도, 자연어로 부탁하면 알아서 구성해 준다.

반환된 결과는 다음과 같았다 (해당 8건 중 5건을 가져옴).

※ 계정명·이메일 주소·본문에 등장하는 다른 사용자의 ID는 숨김 처리하였다.

제목·수신일·본문의 서두까지 그대로 반환된다. 터미널 안에서 수신함을 검색하고 있는 것이다. "그 건이 어떤 메일이었더라"를 Gmail을 열지 않고 해결할 수 있다는 것은 바로 이런 것을 의미했다.

참고로, 이 호출로 반환되는 것은 본문의 서두 (snippet)까지이며, 전문은 별도의 도구를 통해 다시 가져오는 방식이다. 목록에서 대략적인 내용을 파악한 뒤, 필요한 것만 본문을 읽는 흐름이다.

claude.ai 측에서 연결했는데 Claude Code의 /mcp에서 커넥터(connector)가 보이지 않는다면, 공식 문서에 나와 있는 다음 세 가지 패턴을 순서대로 의심해 보는 것이 좋다.

• 로그인 방식이 어긋나 있음 (절차 ①과 동일). /status로 확인하고, 해당 환경 변수를 해제한 뒤 /login으로 다시 선택한다.
• 한 번도 사인인(sign-in)하지 않은 커넥터는 접혀 있음 (Claude Code v2.1.161 이후의 동작). claude.ai 섹션 끝에 있는 「Show unused connectors」라는 행에 접혀 있으며, 이를 선택하면 펼쳐진다 (출처: Claude Code 공식 문서 「Connect Claude Code to tools via MCP」).
• 동일한 URL을 가리키는 로컬 서버가 우선됨. Claude Code 측에 직접 추가한 서버가 있으면, 동일한 URL을 가진 claude.ai의 커넥터는 /mcp 목록에서 hidden(숨김) 처리된다 (출처: 위와 동일).

이메일이라는 민감한 데이터에 접근 권한을 부여하는 이야기이므로, 이 부분은 생략하지 않겠다. 인가(authorization) 화면에는 「메일 전송」 권한도 표시된다. 경계하게 되는 부분이지만, Anthropic의 서포트 기사에는 다음과 같이 적혀 있다.

During authentication, Google's OAuth screen mentions email sending permissions. Claude only reads emails and creates drafts with your explicit approval. The send function is not enabled—all emails must be sent manually through your Gmail account.

(인증 과정에서 Google의 OAuth 화면에는 메일 전송 권한이 언급된다. Claude는 이메일을 읽고 사용자의 명시적인 승인을 받은 후 초안(draft)을 작성할 뿐이다. 전송 기능은 활성화되지 않으며, 모든 이메일은 사용자의 Gmail 계정을 통해 수동으로 전송해야 한다)

즉, 인가 화면에 나타나는 권한 목록과 커넥터가 실제로 할 수 있는 일은 별개라는 뜻이다. Gmail 커넥터는 사양상 전송을 할 수 없다 (초안 작성까지만 가능하다).

서버를 직접 선택해서 구축하고 싶다면 지난번의 로컬 MCP 서버, Google 서비스처럼 "이미 연결되어 있는 장소"를 빌리고 싶다면 이번의 커넥터, 라는 식으로 역할 분담이 되어 있는 것으로 보인다.

코드를 작성하기 전 단계──어떤 정보가 어떤 판단으로 이어지고, 누가 무엇을 기다리고 있는가. 그러한 업무의 흐름은 아직 자신의 머릿속에만 존재한다. AI에게 맡길 수 있는 범위가 넓어질수록, 그 부분을 파악하고 있는 사람의 역량이 앞으로 자신의 강점이 되어갈 것이라고 생각한다. 이번에 메일이라는 "실무 정보가 흐르는 장소"에 손을 뻗은 것도, 그 전 단계를 스스로 확인하고 싶었기 때문이다. 결론을 서두를 생각은 없으며, 지금은 이렇게 하나씩 직접 움직이며 확인해 나가는 단계다.

"Claude Code에 기능을 추가한다"는 실체가 하나가 아니었다는 것이 이번의 가장 큰 발견이었다. 자신의 PC 내부에 구축하는 경로와, 이미 존재하는 계정 연동을 빌려 쓰는 경로. 설정하는 장소도 인증 흐름도 완전히 별개인데, Claude Code 측에서 보면 둘 다 똑같이 /mcp 목록에 나열된다. "저 서비스는 MCP 서버가 없어서 연결할 수 없네"라고 끝내지 않아도 되는 상황이 이로 인해 조금은 늘어날 것이라 생각한다.

• Claude Code 공식 문서 「Connect Claude Code to tools via MCP」 (claude.ai 커넥터 장): https://code.claude.com/docs/en/mcp#use-mcp-servers-from-claude-ai
• Anthropic 지원 「Use Google Workspace connectors」: https://support.claude.com/en/articles/10166901-use-google-workspace-connectors
• Anthropic 지원 「Use connectors to extend Claude's capabilities」: https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities
• Claude Code 설치 (공식 퀵스타트): https://code.claude.com/docs/en/quickstart

개인 블로그(https://mint041223techblog.netlify.app/)에 일상적인 개발에서 깨달은 점들을 자세히 쓰고 있습니다 (외부 사이트로 이동합니다).