mcp-gsuite MCP 서버

Google 제품과 상호 작용하는 MCP 서버입니다.

예시 프롬프트

현재 이 MCP 서버는 다음 기능을 통해 Gmail 및 캘린더 통합을 지원합니다.

일반적인

여러 개의 Google 계정

지메일

Gmail 사용자 정보 가져오기
유연한 검색 기능을 갖춘 이메일 쿼리(예: 읽지 않음, 특정 발신자, 날짜 범위, 첨부 파일 포함)
ID로 전체 이메일 내용 검색
수신자, 제목, 본문 및 참조 옵션을 사용하여 새 초안 이메일을 만듭니다.
임시 이메일 삭제
기존 이메일에 답장합니다(즉시 보내거나 임시 보관함에 저장할 수 있음)
ID를 이용해 여러 개의 이메일을 한 번에 검색합니다.
이메일의 여러 첨부 파일을 로컬 시스템에 저장합니다.

달력

여러 캘린더 관리
지정된 시간 범위 내의 캘린더 이벤트 가져오기
다음을 사용하여 캘린더 이벤트를 만듭니다.
- 제목, 시작/종료 시간
- 선택적인 위치 및 설명
- 선택 참석자
- 사용자 정의 시간대 지원
- 알림 환경 설정
캘린더 이벤트 삭제

시도해 볼 수 있는 프롬프트 예시:

읽지 않은 최신 메시지 검색
Scrum Master로부터 온 이메일 검색
회계에서 모든 이메일을 검색합니다.
ABC에 대한 이메일을 가져와 요약하세요.
앨리스의 마지막 이메일에 좋은 답장을 쓰고 초안을 업로드하세요.
Bob의 이메일에 감사 인사와 함께 답장하세요. 임시 보관함에 보관하세요.
내일 일정은 뭐야?
다음 주 내 개인 계정의 가족 일정을 확인하세요
다음 주에 팀과 2시간 동안의 행사를 계획해야 합니다. 시간대를 제안해 주세요.

빠른 시작

설치하다

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 mcp-gsuite를 자동으로 설치하려면:

지엑스피1

Oauth 2

Google Workspace(G Suite) API를 사용하려면 OAuth2 인증이 필요합니다. 다음 단계에 따라 인증을 설정하세요.

OAuth2 자격 증명을 만듭니다.
- Google Cloud Console 로 이동
- 새 프로젝트를 만들거나 기존 프로젝트를 선택하세요
- 프로젝트에 Gmail API와 Google 캘린더 API를 활성화하세요
- "자격 증명" → "자격 증명 만들기" → "OAuth 클라이언트 ID"로 이동하세요.
- 애플리케이션 유형으로 "데스크톱 앱" 또는 "웹 애플리케이션"을 선택하세요.
- 필수 정보로 OAuth 동의 화면 구성
- 권한이 있는 리디렉션 URI를 추가합니다(로컬 개발을 위해 http://localhost:4100/code 포함)
필요한 OAuth2 범위:

   [
     "openid",
     "https://mail.google.com/",
     "https://www.googleapis.com/auth/calendar",
     "https://www.googleapis.com/auth/userinfo.email"
   ]

그런 다음 클라이언트를 사용하여 작업 디렉토리에 .gauth.json 만듭니다.

{
    "web": {
        "client_id": "$your_client_id",
        "client_secret": "$your_client_secret",
        "redirect_uris": ["http://localhost:4100/code"],
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token"
    }
}

계정 정보가 포함된 .accounts.json 파일을 만듭니다.

{
    "accounts": [
        {
            "email": "alice@bob.com",
            "account_type": "personal",
            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
        }
    ]
}

여러 계정을 지정할 수 있습니다. Google Auth 앱에서 해당 계정에 대한 접근 권한이 있는지 확인하세요. extra_info 필드는 AI에게 계정에 대한 정보(예: 특정 목적 여부)를 제공할 수 있어 특히 유용합니다.

참고: 특정 계정에 대한 도구 중 하나를 처음 실행하면 브라우저가 열리고 Google로 리디렉션되어 사용자 인증 정보, 범위 등을 입력하라는 메시지가 표시됩니다. 로그인에 성공하면 사용자 인증 정보가 .oauth.{email}.json 이라는 로컬 파일에 저장됩니다. 권한이 부여되면 새로 고침 토큰이 사용됩니다.

클로드 데스크탑

MacOS의 경우: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite"
      ]
    }
  }
}

참고: uv run mcp-gsuite --accounts-file /path/to/custom/.accounts.json 사용하여 다른 계정 파일을 지정하거나 --credentials-dir /path/to/custom/credentials 다른 자격 증명 디렉토리를 지정할 수도 있습니다.

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uvx",
      "args": [
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

구성 옵션

MCP 서버는 인증 및 계정 정보에 대한 사용자 정의 경로를 지정하기 위해 여러 명령줄 옵션으로 구성할 수 있습니다.

--gauth-file : OAuth2 클라이언트 구성이 포함된 .gauth.json 파일의 경로를 지정합니다. 기본값은 ./.gauth.json 입니다.
--accounts-file : Google 계정 정보가 포함된 .accounts.json 파일의 경로를 지정합니다. 기본값은 ./.accounts.json 입니다.
--credentials-dir : 인증 성공 후 OAuth 자격 증명이 저장되는 디렉터리를 지정합니다. 기본값은 현재 작업 디렉터리이며, 각 계정의 하위 디렉터리는 .oauth.{email}.json 형식입니다.

이러한 옵션을 사용하면 다양한 환경이나 여러 자격 증명 및 계정 세트를 유연하게 관리할 수 있으며, 특히 개발 및 테스트 시나리오에서 유용합니다.

사용 예:

uv run mcp-gsuite --gauth-file /path/to/custom/.gauth.json --accounts-file /path/to/custom/.accounts.json --credentials-dir /path/to/custom/credentials

이 구성은 서로 다른 구성으로 여러 서버 인스턴스를 실행하거나 기본 경로가 적합하지 않은 환경에 배포할 때 특히 유용합니다.

개발

건축 및 출판

배포를 위해 패키지를 준비하려면:

종속성 동기화 및 잠금 파일 업데이트:

uv sync

패키지 배포 빌드:

uv build

이렇게 하면 dist/ 디렉토리에 소스와 휠 배포판이 생성됩니다.

PyPI에 게시:

uv publish

참고: 환경 변수나 명령 플래그를 통해 PyPI 자격 증명을 설정해야 합니다.

토큰: --token 또는 UV_PUBLISH_TOKEN
또는 사용자 이름/비밀번호: --username / UV_PUBLISH_USERNAME 및 --password / UV_PUBLISH_PASSWORD

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해서는 MCP Inspector 사용을 강력히 권장합니다.

다음 명령을 사용하여 npm 통해 MCP Inspector를 시작할 수 있습니다.

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-gsuite run mcp-gsuite

Inspector를 실행하면 브라우저에서 접근하여 디버깅을 시작할 수 있는 URL이 표시됩니다.

다음 명령을 사용하여 서버 로그를 볼 수도 있습니다.

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-gsuite.log

mcp-gsuite

Integrations