# Google Workspace MCP Server
MCP (Model Context Protocol) server for comprehensive Google Workspace integration with Claude Code and Claude Desktop.
> **Credits**: This project is based on [google-drive-mcp](https://github.com/piotr-agier/google-drive-mcp) by [Piotr Agier](https://github.com/piotr-agier). Extended to support the full Google Workspace suite.
---
**[Español](#español)** | **English**
---
## Features
Full integration with Google Workspace APIs:
| Service | Tools | Status |
|---------|-------|--------|
| **Google Drive** | 14 | Core (always enabled) |
| **Drive Permissions** | 5 | Core (always enabled) |
| **Google Docs** | 4 | Core (always enabled) |
| **Google Sheets** | 6 | Core (always enabled) |
| **Google Slides** | 9 | Core (always enabled) |
| **Google Calendar** | 12 | Opt-in |
| **Gmail** | 24 | Opt-in |
| **Google Meet** | 18 | Opt-in |
| **Google Tasks** | 12 | Opt-in |
| **Google Contacts** | 10 | Opt-in |
**Total: 114 MCP tools**
## Quick Start
### 1. Install dependencies
```bash
npm install
```
### 2. Configure OAuth credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the APIs you need:
- Google Drive API (required)
- Google Docs API (required)
- Google Sheets API (required)
- Google Slides API (required)
- Google Calendar API (optional)
- Gmail API (optional)
- Google Meet API (optional)
- Google Tasks API (optional)
- People API (optional, for Contacts)
4. Create OAuth 2.0 credentials (Desktop app)
5. Download the JSON file and save as `gcp-oauth.keys.json` in the project root
### 3. Authenticate
```bash
# Basic (Drive, Docs, Sheets, Slides)
npm run auth
# With Calendar
GOOGLE_WORKSPACE_CALENDAR=true npm run auth
# With Gmail
GOOGLE_WORKSPACE_GMAIL=true npm run auth
# With Meet
GOOGLE_WORKSPACE_MEET=true npm run auth
# With Tasks
GOOGLE_WORKSPACE_TASKS=true npm run auth
# With Contacts
GOOGLE_WORKSPACE_CONTACTS=true npm run auth
# All services
GOOGLE_WORKSPACE_CALENDAR=true GOOGLE_WORKSPACE_GMAIL=true GOOGLE_WORKSPACE_MEET=true GOOGLE_WORKSPACE_TASKS=true GOOGLE_WORKSPACE_CONTACTS=true npm run auth
```
### 4. Configure Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"google-workspace": {
"command": "node",
"args": ["/path/to/google-workspace-mcp/dist/index.js"],
"env": {
"GOOGLE_WORKSPACE_CALENDAR": "true",
"GOOGLE_WORKSPACE_GMAIL": "true",
"GOOGLE_WORKSPACE_MEET": "true",
"GOOGLE_WORKSPACE_TASKS": "true",
"GOOGLE_WORKSPACE_CONTACTS": "true"
}
}
}
}
```
### 5. Configure Claude Code
Add to your global Claude Code config (`~/.claude.json`):
```json
{
"mcpServers": {
"google-workspace": {
"type": "stdio",
"command": "node",
"args": ["/path/to/google-workspace-mcp/dist/index.js"],
"env": {
"GOOGLE_WORKSPACE_CALENDAR": "true",
"GOOGLE_WORKSPACE_GMAIL": "true",
"GOOGLE_WORKSPACE_MEET": "true",
"GOOGLE_WORKSPACE_TASKS": "true",
"GOOGLE_WORKSPACE_CONTACTS": "true"
}
}
}
}
```
## Tools Reference
### Google Drive (14 tools)
#### Files
| Tool | Description |
|------|-------------|
| `search` | Search files by name, type, or content |
| `createTextFile` | Create text/markdown files |
| `updateTextFile` | Update text file content |
| `deleteFile` | Delete file or folder |
| `renameFile` | Rename file or folder |
| `moveFile` | Move file to another folder |
| `copyFile` | Copy file to another location |
| `uploadBinaryFile` | Upload binary files (PDF, images, etc.) |
| `downloadBinaryFile` | Download files to local disk |
#### Folders
| Tool | Description |
|------|-------------|
| `listFolder` | List folder contents |
| `createFolder` | Create new folder |
| `getAccountInfo` | Get Drive account info |
### Drive Permissions (5 tools)
| Tool | Description |
|------|-------------|
| `drive_listPermissions` | List all sharing permissions for a file |
| `drive_getPermission` | Get details of a specific permission |
| `drive_shareFile` | Share file with user/group/domain/anyone |
| `drive_updatePermission` | Update permission role |
| `drive_unshare` | Remove a permission (stop sharing) |
### Google Docs (4 tools)
| Tool | Description |
|------|-------------|
| `createGoogleDoc` | Create new Google Doc |
| `getGoogleDocContent` | Get document content |
| `updateGoogleDoc` | Update document content |
| `formatGoogleDocText` | Format text in document |
### Google Sheets (8 tools)
| Tool | Description |
|------|-------------|
| `createGoogleSheet` | Create new spreadsheet |
| `getGoogleSheetContent` | Get spreadsheet data |
| `updateGoogleSheet` | Update cell values |
| `formatGoogleSheetCells` | Format cells (background, alignment) |
| `formatGoogleSheetText` | Format text in cells |
| `formatGoogleSheetNumbers` | Apply number formatting |
| `setGoogleSheetBorders` | Set cell borders |
| `mergeGoogleSheetCells` | Merge cells |
### Google Slides (7 tools)
| Tool | Description |
|------|-------------|
| `createGoogleSlides` | Create new presentation |
| `getGoogleSlidesContent` | Get presentation content |
| `updateGoogleSlides` | Update slide content |
| `createGoogleSlidesTextBox` | Add text box to slide |
| `createGoogleSlidesShape` | Add shape to slide |
| `formatGoogleSlidesText` | Format text in slides |
| `setGoogleSlidesBackground` | Set slide background |
### Google Calendar (24 tools)
Enable with `GOOGLE_WORKSPACE_CALENDAR=true`
#### Events
| Tool | Description |
|------|-------------|
| `createCalendarEvent` | Create new event |
| `getCalendarEvent` | Get event details |
| `listCalendarEvents` | List calendar events |
| `updateCalendarEvent` | Update event |
| `deleteCalendarEvent` | Delete event |
| `quickAddEvent` | Quick add event from text |
| `moveCalendarEvent` | Move event to another calendar |
| `getEventInstances` | Get recurring event instances |
#### Calendars
| Tool | Description |
|------|-------------|
| `listCalendars` | List all calendars |
| `getCalendar` | Get calendar details |
| `createCalendar` | Create new calendar |
| `updateCalendar` | Update calendar settings |
| `deleteCalendar` | Delete calendar |
#### Calendar Management
| Tool | Description |
|------|-------------|
| `addCalendarToList` | Add calendar to list |
| `updateCalendarInList` | Update calendar in list |
| `removeCalendarFromList` | Remove calendar from list |
| `shareCalendar` | Share a calendar |
| `getCalendarPermissions` | Get calendar permissions |
| `updateCalendarPermission` | Update calendar permission |
| `removeCalendarPermission` | Remove calendar permission |
| `checkAvailability` | Check free/busy status |
| `getCalendarColors` | Get available colors |
| `getCalendarSettings` | Get calendar settings |
### Gmail (24 tools)
Enable with `GOOGLE_WORKSPACE_GMAIL=true`
#### Messages
| Tool | Description |
|------|-------------|
| `listMessages` | List messages with filters |
| `getMessage` | Get message content |
| `sendMessage` | Send email (with attachments) |
| `replyToMessage` | Reply to a message |
| `forwardMessage` | Forward a message |
| `trashMessage` | Move message to trash |
| `deleteMessage` | Permanently delete message |
| `modifyMessageLabels` | Add/remove labels |
#### Threads
| Tool | Description |
|------|-------------|
| `listThreads` | List email threads |
| `getThread` | Get full thread |
| `trashThread` | Trash entire thread |
| `modifyThreadLabels` | Modify thread labels |
#### Drafts
| Tool | Description |
|------|-------------|
| `listDrafts` | List drafts |
| `createDraft` | Create new draft |
| `updateDraft` | Update draft |
| `sendDraft` | Send draft |
| `deleteDraft` | Delete draft |
#### Labels
| Tool | Description |
|------|-------------|
| `listLabels` | List all labels |
| `createLabel` | Create custom label |
| `updateLabel` | Update label |
| `deleteLabel` | Delete label |
#### Other
| Tool | Description |
|------|-------------|
| `getAttachment` | Download attachment |
| `getVacationSettings` | Get vacation responder |
| `setVacationSettings` | Set vacation responder |
| `getGmailProfile` | Get Gmail profile |
### Google Meet (18 tools)
Enable with `GOOGLE_WORKSPACE_MEET=true`
#### Spaces
| Tool | Description |
|------|-------------|
| `meet_createSpace` | Create meeting space |
| `meet_getSpace` | Get space details |
| `meet_updateSpace` | Update space config |
| `meet_endActiveConference` | End active meeting |
#### Members
| Tool | Description |
|------|-------------|
| `meet_addMember` | Add co-host |
| `meet_listMembers` | List space members |
| `meet_deleteMember` | Remove member |
#### Conference Records
| Tool | Description |
|------|-------------|
| `meet_listConferenceRecords` | List past meetings |
| `meet_getConferenceRecord` | Get meeting details |
#### Participants
| Tool | Description |
|------|-------------|
| `meet_listParticipants` | List attendees |
| `meet_getParticipant` | Get participant info |
| `meet_listParticipantSessions` | Get join/leave times |
#### Recordings
| Tool | Description |
|------|-------------|
| `meet_listRecordings` | List recordings |
| `meet_getRecording` | Get recording URL |
#### Transcripts
| Tool | Description |
|------|-------------|
| `meet_listTranscripts` | List transcripts |
| `meet_getTranscript` | Get transcript details |
| `meet_listTranscriptEntries` | Get transcript text |
### Google Tasks (12 tools)
Enable with `GOOGLE_WORKSPACE_TASKS=true`
#### Task Lists
| Tool | Description |
|------|-------------|
| `tasks_listTaskLists` | List all task lists |
| `tasks_getTaskList` | Get task list details |
| `tasks_createTaskList` | Create new task list |
| `tasks_updateTaskList` | Update task list |
| `tasks_deleteTaskList` | Delete task list |
#### Tasks
| Tool | Description |
|------|-------------|
| `tasks_listTasks` | List tasks in a list |
| `tasks_getTask` | Get task details |
| `tasks_createTask` | Create new task |
| `tasks_updateTask` | Update task |
| `tasks_completeTask` | Mark task as completed |
| `tasks_deleteTask` | Delete task |
| `tasks_clearCompleted` | Clear completed tasks |
### Google Contacts (10 tools)
Enable with `GOOGLE_WORKSPACE_CONTACTS=true`
#### Contacts
| Tool | Description |
|------|-------------|
| `contacts_listContacts` | List all contacts |
| `contacts_getContact` | Get contact details |
| `contacts_searchContacts` | Search contacts |
| `contacts_createContact` | Create new contact |
| `contacts_updateContact` | Update contact |
| `contacts_deleteContact` | Delete contact |
#### Contact Groups
| Tool | Description |
|------|-------------|
| `contacts_listGroups` | List contact groups |
| `contacts_createGroup` | Create contact group |
| `contacts_updateGroup` | Update contact group |
| `contacts_deleteGroup` | Delete contact group |
## Service Configuration
Services can be enabled/disabled via environment variables:
| Service | Environment Variable | Default |
|---------|---------------------|---------|
| Drive | `GOOGLE_WORKSPACE_DRIVE` | `true` |
| Docs | `GOOGLE_WORKSPACE_DOCS` | `true` |
| Sheets | `GOOGLE_WORKSPACE_SHEETS` | `true` |
| Slides | `GOOGLE_WORKSPACE_SLIDES` | `true` |
| Calendar | `GOOGLE_WORKSPACE_CALENDAR` | `false` |
| Gmail | `GOOGLE_WORKSPACE_GMAIL` | `false` |
| Meet | `GOOGLE_WORKSPACE_MEET` | `false` |
| Tasks | `GOOGLE_WORKSPACE_TASKS` | `false` |
| Contacts | `GOOGLE_WORKSPACE_CONTACTS` | `false` |
## OAuth Scopes
The server requests only the scopes needed for enabled services:
| Service | Scopes |
|---------|--------|
| Drive | `drive`, `drive.file`, `drive.readonly` |
| Docs | `documents` |
| Sheets | `spreadsheets` |
| Slides | `presentations` |
| Calendar | `calendar`, `calendar.events` |
| Gmail | `gmail.readonly`, `gmail.send`, `gmail.modify`, `gmail.settings.basic` |
| Meet | `meetings.space.created`, `meetings.space.readonly`, `drive.meet.readonly` |
| Tasks | `tasks` |
| Contacts | `contacts`, `contacts.readonly` |
## Project Structure
```
src/
├── index.ts # Entry point
├── server.ts # MCP server setup
├── auth/ # OAuth2 authentication
│ ├── index.ts
│ ├── client.ts
│ ├── server.ts
│ └── tokenManager.ts
├── config/
│ └── services.ts # Service configuration
├── services/ # API wrappers
│ ├── drive.ts
│ ├── docs.ts
│ ├── sheets.ts
│ ├── slides.ts
│ ├── calendar.ts
│ ├── gmail.ts
│ ├── meet.ts
│ ├── tasks.ts
│ └── contacts.ts
├── tools/ # MCP tool definitions
│ ├── files.ts
│ ├── folders.ts
│ ├── docs.ts
│ ├── sheets.ts
│ ├── slides.ts
│ ├── calendar.ts
│ ├── gmail.ts
│ ├── meet.ts
│ ├── tasks.ts
│ ├── contacts.ts
│ └── permissions.ts
└── utils/
├── paths.ts
└── errors.ts
```
## Development
```bash
# Build
npm run build
# Run authentication
npm run auth
# Run tests
node test-gmail.mjs # Gmail tests
node test-meet.mjs # Meet tests
node test-new-features.mjs # Tasks, Contacts, Permissions tests
```
## Requirements
- Node.js 18+
- Google Cloud project with OAuth credentials
- Google Workspace account (some Meet features require paid Workspace)
## License
MIT
## Credits
- Original project: [google-drive-mcp](https://github.com/piotr-agier/google-drive-mcp) by [Piotr Agier](https://github.com/piotr-agier)
- Extended by: [DonMrMango](https://github.com/donmrmango)
---
# Español
## Google Workspace MCP Server
Servidor MCP (Model Context Protocol) para integración completa de Google Workspace con Claude Code y Claude Desktop.
> **Créditos**: Este proyecto está basado en [google-drive-mcp](https://github.com/piotr-agier/google-drive-mcp) de [Piotr Agier](https://github.com/piotr-agier). Extendido para soportar toda la suite de Google Workspace.
## Características
Integración completa con las APIs de Google Workspace:
| Servicio | Herramientas | Estado |
|----------|--------------|--------|
| **Google Drive** | 14 | Core (siempre habilitado) |
| **Permisos de Drive** | 5 | Core (siempre habilitado) |
| **Google Docs** | 4 | Core (siempre habilitado) |
| **Google Sheets** | 6 | Core (siempre habilitado) |
| **Google Slides** | 9 | Core (siempre habilitado) |
| **Google Calendar** | 12 | Opcional |
| **Gmail** | 24 | Opcional |
| **Google Meet** | 18 | Opcional |
| **Google Tasks** | 12 | Opcional |
| **Google Contacts** | 10 | Opcional |
**Total: 114 herramientas MCP**
## Inicio Rápido
### 1. Instalar dependencias
```bash
npm install
```
### 2. Configurar credenciales OAuth
1. Ir a [Google Cloud Console](https://console.cloud.google.com/)
2. Crear un nuevo proyecto o seleccionar uno existente
3. Habilitar las APIs que necesites:
- Google Drive API (requerida)
- Google Docs API (requerida)
- Google Sheets API (requerida)
- Google Slides API (requerida)
- Google Calendar API (opcional)
- Gmail API (opcional)
- Google Meet API (opcional)
- Google Tasks API (opcional)
- People API (opcional, para Contacts)
4. Crear credenciales OAuth 2.0 (aplicación de escritorio)
5. Descargar el archivo JSON y guardarlo como `gcp-oauth.keys.json` en la raíz del proyecto
### 3. Autenticar
```bash
# Básico (Drive, Docs, Sheets, Slides)
npm run auth
# Con Calendar
GOOGLE_WORKSPACE_CALENDAR=true npm run auth
# Con Gmail
GOOGLE_WORKSPACE_GMAIL=true npm run auth
# Con Meet
GOOGLE_WORKSPACE_MEET=true npm run auth
# Con Tasks
GOOGLE_WORKSPACE_TASKS=true npm run auth
# Con Contacts
GOOGLE_WORKSPACE_CONTACTS=true npm run auth
# Todos los servicios
GOOGLE_WORKSPACE_CALENDAR=true GOOGLE_WORKSPACE_GMAIL=true GOOGLE_WORKSPACE_MEET=true GOOGLE_WORKSPACE_TASKS=true GOOGLE_WORKSPACE_CONTACTS=true npm run auth
```
### 4. Configurar Claude Desktop
Agregar a la configuración de Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"google-workspace": {
"command": "node",
"args": ["/ruta/a/google-workspace-mcp/dist/index.js"],
"env": {
"GOOGLE_WORKSPACE_CALENDAR": "true",
"GOOGLE_WORKSPACE_GMAIL": "true",
"GOOGLE_WORKSPACE_MEET": "true",
"GOOGLE_WORKSPACE_TASKS": "true",
"GOOGLE_WORKSPACE_CONTACTS": "true"
}
}
}
}
```
### 5. Configurar Claude Code
Agregar a la configuración global de Claude Code (`~/.claude.json`):
```json
{
"mcpServers": {
"google-workspace": {
"type": "stdio",
"command": "node",
"args": ["/ruta/a/google-workspace-mcp/dist/index.js"],
"env": {
"GOOGLE_WORKSPACE_CALENDAR": "true",
"GOOGLE_WORKSPACE_GMAIL": "true",
"GOOGLE_WORKSPACE_MEET": "true",
"GOOGLE_WORKSPACE_TASKS": "true",
"GOOGLE_WORKSPACE_CONTACTS": "true"
}
}
}
}
```
## Configuración de Servicios
Los servicios se pueden habilitar/deshabilitar mediante variables de entorno:
| Servicio | Variable de Entorno | Por Defecto |
|----------|---------------------|-------------|
| Drive | `GOOGLE_WORKSPACE_DRIVE` | `true` |
| Docs | `GOOGLE_WORKSPACE_DOCS` | `true` |
| Sheets | `GOOGLE_WORKSPACE_SHEETS` | `true` |
| Slides | `GOOGLE_WORKSPACE_SLIDES` | `true` |
| Calendar | `GOOGLE_WORKSPACE_CALENDAR` | `false` |
| Gmail | `GOOGLE_WORKSPACE_GMAIL` | `false` |
| Meet | `GOOGLE_WORKSPACE_MEET` | `false` |
| Tasks | `GOOGLE_WORKSPACE_TASKS` | `false` |
| Contacts | `GOOGLE_WORKSPACE_CONTACTS` | `false` |
## Requisitos
- Node.js 18+
- Proyecto de Google Cloud con credenciales OAuth
- Cuenta de Google Workspace (algunas funciones de Meet requieren Workspace de pago)
## Licencia
MIT
## Créditos
- Proyecto original: [google-drive-mcp](https://github.com/piotr-agier/google-drive-mcp) por [Piotr Agier](https://github.com/piotr-agier)
- Extendido por: [DonMrMango](https://github.com/donmrmango)
