Google Workspace MCP 서버

모델 컨텍스트 프로토콜을 통해 MCP 클라이언트, AI 어시스턴트 등을 Google Workspace 서비스에 연결합니다.

실제로 확인해 보세요:

📑 목차

• 개요

• 특징

• 빠른 시작

  • 필수 조건

  • 설치

  • 구성

  • 서버 시작

  • 서버에 연결

  • Open WebUI와의 통합

  • 최초 인증

• 사용 가능한 도구

  • 달력

  • 구글 드라이브

  • 지메일

  • 구글 문서

• 개발

  • 프로젝트 구조

  • OAuth에 대한 포트 처리

  • 디버깅

  • 새로운 도구 추가

• 보안 참고 사항

• 특허

🌐 개요

Google Workspace MCP 서버는 모델 컨텍스트 프로토콜(MCP)을 사용하여 Google Workspace 서비스(캘린더, 드라이브, Gmail, 문서)를 AI 어시스턴트 및 기타 애플리케이션과 통합합니다. 이를 통해 AI 시스템은 Google Workspace 애플리케이션의 사용자 데이터에 안전하고 효율적으로 액세스하고 상호작용할 수 있습니다.

✨ 특징

• 🔐 OAuth 2.0 인증 : 자동 토큰 새로 고침 및 중앙화된 인증 흐름을 통해 사용자 승인 자격 증명을 사용하여 Google API에 안전하게 연결합니다.

• 📅 Google 캘린더 통합 : 전체 캘린더 관리 - 캘린더 목록, 이벤트 가져오기, 하루 종일 및 시간별 이벤트 지원을 통한 이벤트 생성/수정/삭제

• 📁 Google 드라이브 통합 : 파일 검색, 폴더 내용 나열, 파일 내용 읽기, 새 파일 생성 기능을 제공합니다. .docx, .xlsx 및 기타 Microsoft Office 형식의 추출 및 검색을 기본적으로 지원합니다!

• 📧 Gmail 통합 : 완벽한 이메일 관리 - 모든 쿼리 구문에 대한 완벽한 지원을 통해 메시지 검색, 콘텐츠 검색, 이메일 보내기, 초안 작성

• 📄 Google Docs 통합 : 채팅에서 바로 문서 검색, 문서 내용 읽기, 폴더에 문서 나열, 새 문서 만들기가 가능합니다!

• 🔄 다양한 전송 옵션 : 스트리밍 가능한 HTTP + SSE 폴백

• 🔌 : Open WebUI와 같은 도구와 통합하기 위해 서버를 OpenAPI 엔드포인트로 쉽게 노출합니다.

• 🧩 확장 가능한 디자인 : 더 많은 Google Workspace API 및 도구에 대한 지원을 추가하기 위한 간단한 구조

• 🔄 통합 OAuth 콜백 : 포트 8000에서 서버 내에서 직접 OAuth 리디렉션을 처리합니다.

• ⚡ 스레드 안전 세션 관리 : 향상된 안정성을 위한 스레드 안전 아키텍처를 통한 강력한 세션 처리

🚀 빠른 시작

필수 조건

• 파이썬 3.11+

• uv 패키지 설치 프로그램(또는 pip)

• 필수 API(캘린더, 드라이브, Gmail, 문서)에 대해 OAuth 2.0 자격 증명이 활성화된 Google Cloud Project

설치

지엑스피1

구성

1. Google Cloud Console 에서 OAuth 2.0 자격 증명 (데스크톱 애플리케이션 유형)을 만듭니다.

2. 프로젝트에 Google 캘린더 API , Google 드라이브 API , Gmail API , Google 문서 API를 활성화하세요.

3. OAuth 클라이언트 자격 증명을 client_secret.json 으로 다운로드하여 프로젝트의 루트 디렉토리에 넣습니다.

4. Google Cloud Console에서 OAuth 클라이언트 구성에 다음 리디렉션 URI를 추가합니다. 기본 URI 및 포트는 http://localhost:8000 이며, 환경 변수( WORKSPACE_MCP_BASE_URI 및 WORKSPACE_MCP_PORT )를 통해 사용자 지정할 수 있습니다. 이 변수를 변경하는 경우 Google Cloud Console의 리디렉션 URI도 그에 맞게 업데이트해야 합니다.

   http://localhost:8000/oauth2callback

5. ⚠️ 중요 : client_secret.json``.gitignore 파일에 추가하고 버전 제어에 커밋하지 마세요.

서버 구성

서버의 기본 URL과 포트는 환경 변수를 사용하여 사용자 정의할 수 있습니다.

• WORKSPACE_MCP_BASE_URI : 서버의 기본 URI를 설정합니다(기본값: http://localhost ). 이는 Gemini 네이티브 함수 호출에 사용되는 server_url 과 OAUTH_REDIRECT_URI 에 영향을 미칩니다.

• WORKSPACE_MCP_PORT : 서버가 수신하는 포트를 설정합니다(기본값: 8000 ). 이는 server_url , port 및 OAUTH_REDIRECT_URI 영향을 미칩니다.

사용 예:

환경 설정

서버는 개발 중에 로컬호스트 OAuth 콜백에 HTTP를 사용합니다. 서버를 실행하기 전에 다음 환경 변수를 설정하세요.

이 설정이 없으면 인증 흐름 중에 "OAuth 2는 HTTPS를 활용해야 합니다"라는 오류가 발생할 수 있습니다.

서버 시작

다음 방법 중 하나를 선택하여 서버를 실행하세요.

포트 8000에서 HTTP 전송 계층으로 서버를 실행합니다.

다중 사용자 MCP는 다소 복잡하기 때문에 현재로서는 클라이언트와 서버 간의 1:1 매핑이 가장 원활하게 작동합니다. 하지만 Claude가 OAuth 2.1 플로우를 수행할 수 있게 되면 상황이 달라질 것입니다. 따라서 이 MCP는 간소화된 단일 사용자 환경을 위한 플래그를 사용하여 구축되었습니다. 서버를 단일 사용자 모드로 실행할 수 있으며, 이 모드에서는 세션-OAuth 매핑을 우회하고 .credentials 디렉터리의 사용 가능한 자격 증명을 사용합니다.

단일 사용자 모드에서:

• 서버는 .credentials 디렉토리에서 유효한 자격 증명을 자동으로 찾아 사용합니다.

• 세션 매핑이 필요하지 않습니다. 서버는 발견된 첫 번째 유효한 자격 증명 파일을 사용합니다.

• 개발, 테스트 또는 단일 사용자 배포에 유용합니다.

• 자격 증명 파일을 생성하려면 초기 OAuth 인증이 필요합니다.

이 모드는 다중 사용자 세션 관리가 필요하지 않고 자격 증명 처리를 간소화하려는 경우에 특히 유용합니다.

제공된 Dockerfile 사용하여 서버를 빌드하고 실행할 수 있습니다.

smithery.yaml 파일은 Docker 컨테이너 내에서 서버를 올바르게 시작하도록 구성되어 있습니다.

중요 항구

기본 포트는 8000 이지만 WORKSPACE_MCP_PORT 환경 변수를 통해 변경할 수 있습니다.

서버에 연결

서버는 여러 가지 연결 방법을 지원합니다.

클로드 데스크탑:

어디서나 실행할 수 있으며 mcp-remote 통해 사용하거나 uv run main.py 인수로 사용하여 로컬에서 호출하거나 localhost에서 mcp-remote 사용하여 로컬에서 호출할 수 있습니다.

config.json:

1. mcpo 설치 : uv pip install mcpo 또는 pip install mcpo

2. config.json 생성합니다( Open WebUI와의 통합 참조)

3. config를 가리키는 mcpo 실행합니다: uvx mcpo --config config.json --port 8001

4. MCP 서버 API는 http://localhost:8001/google_workspace (또는 config.json 에 정의된 이름)에서 사용할 수 있습니다.

5. OpenAPI 문서(Swagger UI)는 다음에서 확인할 수 있습니다: http://localhost:8001/google_workspace/docs

시작 명령(단일 MCP MCPO 사용의 경우):

1. mcpo 설치 : uv pip install mcpo 또는 pip install mcpo

2. uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp 로 시작합니다.

3. MCP 서버 API는 http://localhost:8001/openapi.json (또는 config.json 에 정의된 이름)에서 사용할 수 있습니다.

4. OpenAPI 문서(Swagger UI)는 다음에서 확인할 수 있습니다: http://localhost:8001/docs

5. HTTP 모드에서 서버를 시작합니다( 서버 시작 참조)

6. MCP JSON 요청을 http://localhost:8000 으로 직접 보냅니다.

7. curl 이나 사용자 정의 HTTP 클라이언트와 같은 도구를 사용하여 테스트하는 데 유용합니다.

8. Claude Desktop 및 기타 MCP 클라이언트에 mcp-remote를 통한 새로운 Streamable HTTP 전송을 통합하는 데 사용할 수 있습니다.

9. 원하는 경우 SSE 대체 모드로 서비스할 수도 있습니다.

Open WebUI와의 통합

Open WebUI 내에서 이 서버를 도구 공급자로 사용하려면:

1. mcpo : 다음 구조의 config.json 이라는 파일을 만들어 mcpo가 스트리밍 가능한 HTTP 엔드포인트를 OpenAPI 사양 도구로 사용할 수 있도록 합니다.

   { "mcpServers": { "google_workspace": { "type": "streamablehttp", "url": "http://localhost:8000/mcp" } } }

2. mcpo .

   mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"

   이 명령은 mcpo 프록시를 시작하여 포트 8001에서 활성(포트 8000이라고 가정) Google Workspace MCP를 제공합니다.

3. Open WebUI 구성 :

   • Open WebUI 설정으로 이동합니다.

   • "연결" -> "도구"로 이동하세요.

   • "도구 추가"를 클릭하세요

   • 서버 URL을 입력하세요: http://localhost:8001/google_workspace ( config.json 의 mcpo 기본 URL 및 서버 이름과 일치)

   • mcpo 와 함께 --api-key 사용한 경우 API 키로 입력하세요.

   • 구성을 저장합니다

   • 이제 Open WebUI에서 모델과 상호 작용할 때 Google Workspace 도구를 사용할 수 있습니다.

최초 인증

Google API 액세스가 필요한 도구가 호출되는 경우:

• 도구에 : 서버가 자동으로 OAuth 2.0 흐름을 시작합니다. 권한 부여 URL은 MCP 응답으로 반환되거나 콘솔에 출력됩니다.

• user_google_email : 도구는 LLM이 중앙화된 start_google_auth 도구를 사용하도록 안내하는 오류 메시지를 반환합니다. 그런 다음 LLM은 사용자 이메일과 적절한 service_name (예: "Google 캘린더", "Google 문서", "Gmail", "Google 드라이브")을 사용하여 start_google_auth 호출해야 합니다. 이 명령은 또한 승인 URL을 반환합니다.

사용자를 위한 단계(권한 URL을 얻은 후):

1. 제공된 권한 부여 URL을 웹 브라우저에서 엽니다.

2. Google 계정에 로그인하여 지정된 서비스에 대해 요청된 권한을 부여합니다.

3. 인증 후 Google은 브라우저를 http://localhost:8000/oauth2callback (또는 구성된 리디렉션 URI)으로 리디렉션합니다.

4. MCP 서버는 이 콜백을 처리하고, 승인 코드를 토큰으로 교환하고, 자격 증명을 안전하게 저장합니다.

5. 그러면 LLM은 원래 요청을 다시 시도할 수 있습니다. 이후 동일한 사용자 및 서비스에 대한 호출은 새로 고침 토큰이 만료되거나 취소될 때까지 재인증 없이 작동해야 합니다.

🧰 사용 가능한 도구

참고 : 특정 Google 서비스에 대한 도구를 처음 사용할 때 유효한 자격 증명이 저장되어 있지 않고 user_google_email 도구에 제공된 경우 OAuth 인증 흐름이 트리거될 수 있습니다. 인증이 필요하지만 user_google_email 도구에 제공되지 않은 경우, LLM은 사용자 이메일과 적절한 service_name 사용하여 core/server.py 에 정의된 중앙화된 start_google_auth 도구를 사용해야 합니다.

📅 구글 캘린더

출처: gcalendar/calendar_tools.py

ℹ️ 모든 캘린더 도구는 현재 MCP 세션( mcp_session_id )을 통한 인증 또는 user_google_email 을 통한 대체 인증을 지원합니다. 두 방법 모두 사용할 수 없고 인증이 필요한 경우, 도구는 오류를 반환하고 LLM에 사용자 이메일과 service_name="Google Calendar" 사용하여 중앙화된 start_google_auth 도구를 사용하라고 요청합니다.

🕒 날짜/시간 매개변수: 도구는 전체 RFC3339 타임스탬프(예: 2024-05-12T10:00:00Z)와 간단한 날짜(예: 2024-05-12)를 모두 허용합니다. 서버는 필요에 따라 자동으로 형식을 지정합니다.

📁 구글 드라이브

출처: gdrive/drive_tools.py

쿼리 구문 : Google Drive 검색 쿼리의 경우 Drive 검색 쿼리 구문을 참조하세요.

📧 지메일

출처: gmail/gmail_tools.py

쿼리 구문 : Gmail 검색 쿼리의 경우 Gmail 검색 쿼리 구문을 참조하세요.

📝 구글 문서

출처: gdocs/docs_tools.py

🛠️ 개발

프로젝트 구조

OAuth에 대한 포트 처리

서버는 별도의 웹 서버 프레임워크가 필요 없이 OAuth 2.0 리디렉션 URI( /oauth2callback )를 똑똑하게 처리합니다.

• HTTP 모드 또는 mcpo 통해 실행될 때 기본 MCP 라이브러리의 내장 HTTP 서버 기능을 활용합니다.

• 사용자 지정 MCP 경로는 포트 8000 의 /oauth2callback 에 대해 특별히 등록됩니다.

• Google이 승인 후 사용자를 다시 리디렉션하면 MCP 서버는 이 경로에서 요청을 가로채게 됩니다.

• auth 모듈은 승인 코드를 추출하고 토큰 교환을 완료합니다.

• 로컬에서 실행할 경우 콜백이 http://localhost 사용하므로 OAUTHLIB_INSECURE_TRANSPORT=1 설정해야 합니다.

디버깅

인증 단계 및 API 호출을 포함한 자세한 로그는 mcp_server_debug.log 확인하세요. 필요한 경우 디버그 로깅을 활성화하세요.

• client_secret.json 이 올바르고 존재하는지 확인하세요.

• Google Cloud Console에서 올바른 리디렉션 URI( http://localhost:8000/oauth2callback )가 구성되었는지 확인하세요.

• Google Cloud 프로젝트에서 필요한 API(캘린더, 드라이브, Gmail)가 활성화되어 있는지 확인하세요.

• 서버 프로세스가 실행되는 환경에서 OAUTHLIB_INSECURE_TRANSPORT=1 설정되어 있는지 확인하세요.

• 브라우저 기반 OAuth 흐름 중 특정 오류 메시지를 찾아보세요.

Google API에서 반환된 추적 정보나 오류 메시지를 서버 로그에서 확인하세요.

새로운 도구 추가

1. 적절한 모듈을 선택하거나 생성합니다(예: gdocs/gdocs_tools.py )

2. 필요한 라이브러리(Google API 클라이언트 라이브러리 등)를 가져옵니다.

3. 도구 로직에 대한 async 함수를 정의하세요. 매개변수에 대한 유형 힌트를 사용하세요.

4. @server.tool("your_tool_name") 로 함수를 장식하세요.

5. 함수 내부에서 인증된 자격 증명을 가져옵니다.

6. Google API 서비스 클라이언트를 빌드합니다. service = build('drive', 'v3', credentials=credentials)

7. Google API를 호출하는 로직을 구현합니다.

8. 잠재적 오류를 우아하게 처리하세요

9. 결과를 JSON 직렬화 가능 사전 또는 목록으로 반환합니다.

10. 서버에 등록되도록 main.py 에 도구 함수를 가져옵니다.

11. 도구 모듈에서 필요한 서비스별 범위 상수를 정의합니다.

12. 새로운 종속성이 필요한 경우 pyproject.toml 업데이트하세요.

범위 관리 : config/google_config.py 의 전역 SCOPES 목록은 초기 OAuth 동의 화면에 사용됩니다. 각 도구는 get_credentials 호출할 때 필요한 최소한의 필수 required_scopes 요청해야 합니다.

🔒 보안 참고 사항

• client_secret.json : 이 파일에는 민감한 자격 증명이 포함되어 있습니다. 버전 관리 시스템에 절대 커밋 하지 마세요 . .gitignore 파일에 등록하고 안전하게 보관하세요.

• 사용자 토큰 : 인증된 사용자 자격 증명(갱신 토큰)은 credentials-<user_id_hash>.json 과 같은 파일에 로컬로 저장됩니다. 이 파일은 사용자의 Google 계정 데이터에 대한 접근 권한을 부여하므로 안전하게 보호해야 합니다. 또한 .gitignore 파일에도 저장해야 합니다.

• OAuth 콜백 보안 : 개발 중 설치된 애플리케이션의 경우 OAuth 콜백에 http://localhost 를 사용하는 것이 표준이지만, OAUTHLIB_INSECURE_TRANSPORT=1 필요합니다. 로컬호스트 외부에서 운영 환경을 배포하는 경우, 콜백 URI에 HTTPS를 사용하고 Google Cloud Console에서 이를 적절히 설정 해야 합니다 .

• mcpo : mcpo 사용하여 네트워크를 통해 서버를 노출하는 경우 다음 사항을 고려하세요.

  • 기본 인증을 위해 --api-key 옵션 사용

  • HTTPS 종료, 적절한 로깅 및 보다 강력한 인증을 처리하기 위해 역방향 프록시(예: Nginx 또는 Caddy) 뒤에서 mcpo 실행

  • 로컬호스트를 넘어 노출하는 경우 신뢰할 수 있는 네트워크 인터페이스에만 mcpo 바인딩합니다.

• 범위 관리 : 서버는 캘린더, 드라이브, Gmail에 대한 특정 OAuth 범위(권한)를 요청합니다. 사용자는 초기 인증 과정에서 이러한 범위에 따라 접근 권한을 부여합니다. 구현된 도구에 필요한 것보다 더 넓은 범위를 요청하지 마세요.

스크린샷:

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.