gmail-multi-mcp-server

Claude를 여러 Gmail 계정에 동시에 연결하는 MCP 서버로, 기본 제공 Gmail 커넥터와 동일한 도구 표면을 노출합니다. 모든 도구는 어느 사서함을 대상으로 할지 지정하는 추가 account 인수를 받습니다. 이것이 단일 사서함 커넥터와의 유일한 구조적 차이입니다.

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

왜 필요한가

기본 제공 Gmail 커넥터는 하나의 사서함만 인증합니다. 업무용, 개인용, 회사 별칭 등 계정을 분리해서 사용한다면 계속 전환해야 합니다. 이 서버는 사용자가 인증한 수만큼의 Gmail 계정 자격 증명을 보관하고, 각 호출을 사용자가 지정한 계정으로 라우팅합니다.

Related MCP server: multiGmailMCP

요구 사항

• Node.js 20 이상

• Gmail API가 사용 설정된 Google Cloud 프로젝트와 데스크톱 앱 유형의 OAuth 클라이언트

1. Google OAuth 클라이언트 받기

1. Google Cloud Console을 열고 프로젝트를 선택하거나 생성합니다.

2. **APIs & Services → Library →**에서 Gmail API를 사용 설정합니다.

3. **APIs & Services → OAuth consent screen →**에서 구성합니다. 앱이 Testing 상태인 동안 연결하려는 모든 Gmail 주소를 Test users에 추가합니다.

4. **APIs & Services → Credentials → Create credentials → OAuth client ID →**에서 애플리케이션 유형을 데스크톱 앱으로 선택합니다. JSON을 다운로드합니다.

데스크톱 앱 클라이언트는 모든 포트에서 루프백 리디렉션을 허용하며, add-account 흐름이 이를 사용합니다.

2. 설치 및 빌드

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. 서버가 OAuth 클라이언트를 가리키도록 설정

하나를 선택하세요:

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. 각 사서함 인증

Gmail 계정마다 한 번씩 실행하세요:

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

각 실행은 Google 동의 URL을 출력하고, 로컬 루프백 포트에서 리디렉션을 기다린 다음, 결과 리프레시 토큰을 저장합니다. 헤드리스 머신에서는 --manual을 추가하고 리디렉션된 URL을 다시 붙여넣으세요.

서버가 실행되는 동안 추가된 계정은 자동으로 인식됩니다. 재시작할 필요가 없습니다.

5. Claude에 연결

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop — claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

계정 선택

list_accounts를 제외한 모든 도구는 account를 받습니다. 다음 순서로 일치합니다:

1. 전체 이메일 주소 — mikael@example.com

2. add-account 시점에 설정한 별칭 — work

3. @ 앞의 로컬 부분 — mikael

4. 모호하지 않은 모든 접두어

account는 사서함이 하나만 구성된 경우, 또는 GMAIL_MCP_DEFAULT_ACCOUNT가 설정된 경우 선택 사항입니다. 그 외에는 필수이며, 오류 메시지에 사용 가능한 항목이 나열됩니다.

ID는 사서함별로 다릅니다. 한 계정의 메시지, 스레드, 초안 또는 라벨 ID는 다른 계정에서는 의미가 없습니다. "not found" 오류는 보통 잘못된 account가 전달되었음을 의미합니다.

도구

35개 도구 — 커넥터의 도구 구성에 멀티 계정용 두 개가 추가된 것입니다.

도구 이름은 의도적으로 Gmail 커넥터와 일치하므로 프롬프트와 사용 습관을 그대로 이어갈 수 있습니다. MCP 클라이언트는 도구를 서버별로 네임스페이스하므로 두 서버를 동시에 활성화해도 충돌하지 않습니다.

기본 제공 커넥터와의 차이점

아래는 모두 추가된 내용입니다. 커넥터가 수행하는 동작 중 여기서 다르게 동작하는 것은 없습니다.

• **account**가 모든 도구에 추가되었으며, list_accounts와 get_profile도 추가되었습니다.

• response_format (markdown | json)이 모든 도구에 추가되었습니다. 기본값은 markdown이며 간결함을 유지합니다. 어느 쪽이든 전체 구조화 페이로드는 structuredContent로 반환됩니다.

• **delete_draft**와 **get_message_attachment**는 커넥터가 참조하지만 노출하지 않는 도구입니다.

• **reply**는 quoteOriginal(기본값 false)을 받아 원본을 인용 블록으로 덧붙입니다.

• **forward**는 includeAttachments(기본값 true)를 받습니다. 큰 파일을 건너뛰려면 false로 설정하세요.

• **get_message_attachment**는 savePath를 받아 base64를 인라인하는 대신 파일을 디스크에 저장합니다.

• 응답은 25,000자로 제한되며, 페이지네이션된 목록을 먼저 줄인 다음 무엇이 생략되었는지와 나머지를 얻는 방법을 정확히 알려줍니다.

알아 두면 좋은 동작

• search_threads는 커넥터와 마찬가지로 각 스레드의 가장 오래된 메시지(~5개)의 미리보기를 반환합니다. 최근 메일이나 읽지 않은 메일에 대해 답하기 전에 get_thread를 호출하세요.

• 초안은 쿼리에 초안이 언급되지 않는 한 search_threads에서 제외됩니다. list_drafts를 사용하세요.

• 라벨은 표시 이름이 아닌 ID로 지정합니다. 먼저 list_labels를 호출하세요.

• DRAFT와 SENT는 읽기 전용입니다. TRASH/SPAM 추가는 apply_sensitive_* 도구로 라우팅되므로 파괴적인 작업은 항상 명시적으로 이름이 지정됩니다.

• update_draft는 필드를 병합하지만 첨부 파일은 병합되지 않고 교체됩니다 — 응답은 몇 개가 삭제되었는지 보고합니다.

• reply는 In-Reply-To와 References를 설정하여 클라이언트가 올바르게 스레드로 묶이도록 하며, 인증된 사서함 자신에게 답장을 보내지 않습니다.

보안

• 리프레시 토큰은 ~/.gmail-mcp/accounts.json에 저장되며, 0700 디렉터리 안에 0600 권한으로 원자적으로 기록됩니다. 이 파일에 읽기 권한이 있는 사람은 사서함에 대한 전체 액세스 권한을 갖게 됩니다.

• OAuth 흐름은 state 매개변수를 검증하고 127.0.0.1에서만 수신 대기합니다.

• remove-account는 로컬 토큰을 삭제합니다. 완전히 철회하려면 myaccount.google.com/permissions에서 앱도 제거하세요.

• 부여된 권한 범위는 메일 읽기, 보내기, 삭제를 허용합니다. send_message, reply, forward는 즉시 전송됩니다. 도구 설명은 사용자가 메일 발송을 명확히 요청하지 않은 경우 create_draft를 우선하도록 모델에 지시합니다.

개발

npm run build         # compile TypeScript to dist/
npm test              # build, then unit tests + stdio smoke test
npm run test:unit     # MIME, reply addressing, parsing, truncation — no network
npm run test:smoke    # boots the server, checks all 35 tools register
npm run inspect       # open the MCP Inspector against the server

src/
  index.ts            CLI entry point and server bootstrap
  constants.ts        scopes, limits, paths
  types.ts            normalized message/thread/draft shapes
  auth/               token store, OAuth flow, account registry
  schemas/common.ts   shared Zod fields (account, formats, pagination, colors)
  services/           Gmail parsing, MIME building, formatting, errors
  tools/              tool registration by domain

문제 해결

라이선스

MIT