# 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)