gworkspace-mcp

Google Workspace 자동화(Google Sheets, Apps Script, Drive, Docs, Gmail 및 트리거)를 위한 Model Context Protocol 서버입니다. FastMCP로 구축되었습니다.

Claude Code(또는 모든 MCP 호환 클라이언트)에서 사용하도록 설계되어, 대화 중에 직접 Apps Script 프로젝트를 편집하고, 스프레드시트를 조작하며, 이메일을 보내고, Drive 파일을 관리할 수 있습니다.

기능

Apps Script (9개 도구) — Apps Script 프로젝트 나열, 읽기, 업데이트, 생성, 배포 및 실행. 전체 스크립트를 다시 작성할 필요 없이 세밀한 파일 편집이 가능합니다.
Sheets (10개 도구) — 범위 읽기/쓰기, 일괄 업데이트, 서식 지정, 보호, 수식, 대시보드.
Drive (4개 도구) — 파일 나열, 검색, 이동 및 관리.
Docs (1개 도구) — Google Docs 읽기/편집.
Gmail (3개 도구) — 이메일 작성 및 전송.
Triggers (3개 도구) — Apps Script 시간 기반 및 이벤트 트리거 관리.
Connect (1개 도구) — 로컬 Apps Script 프로젝트를 스프레드시트에 바인딩.

요구 사항

Python 3.10+
다음 API가 활성화된 Google Cloud 프로젝트:
- Google Sheets API
- Google Drive API
- Apps Script API
- Google Docs API
- Gmail API
- Google Calendar API
OAuth 2.0 데스크톱 자격 증명 (client_secret.json)

설치

git clone https://github.com/LeooNic/gworkspace-mcp.git
cd gworkspace-mcp
pip install -e .

또는 uv 사용 시:

uv pip install -e .

Google Cloud 설정

console.cloud.google.com으로 이동하여 프로젝트를 생성합니다.
API 및 서비스 → 라이브러리에서 위에 나열된 API를 활성화합니다.
API 및 서비스 → OAuth 동의 화면으로 이동하여 **외부(External)**로 구성하고, Google 계정을 테스트 사용자로 추가합니다.
API 및 서비스 → 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID로 이동하여 **데스크톱 앱(Desktop app)**을 선택하고 JSON을 다운로드합니다.
다음 방법 중 하나로 서버에서 자격 증명을 사용할 수 있도록 설정합니다:
- JSON을 ~/.secrets/gworkspace-mcp/client_secret.json에 배치하거나,
- GOOGLE_CLIENT_SECRET_PATH=/full/path/to/client_secret.json을 설정하거나,
- GOOGLE_OAUTH_CLIENT_ID 및 GOOGLE_OAUTH_CLIENT_SECRET을 환경 변수로 설정합니다.

도구가 처음 실행될 때 OAuth 동의를 위한 브라우저 창이 열립니다. 결과 토큰은 ~/.secrets/gworkspace-mcp/token.json에 저장되며 자동으로 갱신됩니다.

Claude Code에 등록

Claude Code의 settings.json(또는 ~/.claude.json)에 다음을 추가합니다:

{
  "mcpServers": {
    "gworkspace": {
      "command": "gworkspace-mcp"
    }
  }
}

gworkspace-mcp가 PATH에 없는 경우, pip install -e .로 생성된 실행 파일의 절대 경로를 사용하세요(Windows의 경우 일반적으로 C:\Users\<사용자>\AppData\Local\Programs\Python\Python3XX\Scripts\gworkspace-mcp.exe).

진입점을 설치하지 않고 호출하는 대안:

{
  "mcpServers": {
    "gworkspace": {
      "command": "python",
      "args": ["-m", "gworkspace_mcp.server"]
    }
  }
}

OAuth 범위

서버는 다음 범위를 요청합니다:

spreadsheets, drive, documents, calendar
script.projects, script.deployments, script.processes, script.metrics
gmail.send, gmail.compose
userinfo.email, userinfo.profile

보안 참고 사항

client_secret.json 및 token.json은 개인 정보이므로 절대 커밋하지 마십시오. 저장소의 .gitignore에는 이미 제외되어 있습니다.
토큰은 ~/.secrets/gworkspace-mcp/ 아래에 저장됩니다.
서버는 로컬에서 실행되며 네트워크 엔드포인트를 노출하지 않습니다.