google-chat-mcp

Google Chat용 MCP 서버입니다. Claude(Code / Desktop) 또는 모든 MCP 클라이언트가 내 스페이스를 나열하고, 메시지를 읽고 검색하며, 스레드와 멤버를 가져올 수 있고, 선택적으로(opt-in) 사용자 대신 메시지를 보낼 수도 있습니다.

기본적으로 읽기 전용입니다. stdio를 통해 로컬에서 실행됩니다. 새로고침 토큰은 ~/.google-chat-mcp/ 아래에 0600 권한으로 저장됩니다.

도구

보낸 사람 이름은 People API 디렉터리(directory.readonly)에서 가져옵니다. 해당 API가 비활성화되어 있거나 사용자가 외부 사용자인 경우 users/<id>가 대신 표시되며, 그 외에는 모든 기능이 정상 작동합니다.

Related MCP server: Google Chat MCP Server

설정

Google Workspace 계정이 필요합니다. 일반 @gmail.com 계정은 Chat API를 호출할 수 없습니다(403).

1. Google Cloud 프로젝트(1회, 약 10분)

1. console.cloud.google.com → 프로젝트 생성/선택.

2. API 및 서비스 → 라이브러리 → Google Chat API 및 People API 사용 설정.

3. Google Chat API → 구성 탭 → 앱 이름, 아바타 URL, 설명 입력, 대화형 기능 끄기, 도메인에 공개로 설정. 저장.

   주의: 이 양식을 저장하기 전까지 Chat API는 읽기 전용 사용자 인증을 포함한 모든 OAuth 호출을 403으로 거부합니다.

4. OAuth 동의 화면 → 내부 → 범위 추가:

   • https://www.googleapis.com/auth/chat.spaces.readonly

   • https://www.googleapis.com/auth/chat.messages.readonly

   • https://www.googleapis.com/auth/chat.memberships.readonly

   • https://www.googleapis.com/auth/directory.readonly

   • https://www.googleapis.com/auth/chat.messages.create (send_message를 원하는 경우에만)

5. 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID → 데스크톱 앱 → JSON 다운로드. 저장소에 포함하지 마세요.

2. 로그인

export GOOGLE_CHAT_CLIENT_SECRET_PATH=/path/to/client_secret.json
npx google-chat-mcp login        # browser opens → sign in with your Workspace account
npx google-chat-mcp whoami       # sanity check

3. Claude Code에 등록

claude mcp add google-chat \
  -e GOOGLE_CHAT_CLIENT_SECRET_PATH=/path/to/client_secret.json \
  -- npx -y google-chat-mcp

Claude Desktop(claude_desktop_config.json):

{
  "mcpServers": {
    "google-chat": {
      "command": "npx",
      "args": ["-y", "google-chat-mcp"],
      "env": { "GOOGLE_CHAT_CLIENT_SECRET_PATH": "/path/to/client_secret.json" }
    }
  }
}

환경 변수

할당량 참고 사항

Chat API: 사용자당 분당 약 60회 요청. 스페이스 및 멤버 목록은 프로세스 내에서 5분간 캐시되며, 확인된 사용자 이름은 ~/.google-chat-mcp/users.json에 디스크에 캐시됩니다. search_messages가 가장 비용이 많이 드는 작업이므로 spaces와 since로 범위를 제한하세요.

개발

pnpm install
pnpm dev login
pnpm typecheck && pnpm lint && pnpm build

Node ≥ 22. TypeScript strict, ESM, tsup 빌드.

라이선스

MIT