# Google Workspace MCP Server

A TypeScript MCP (Model Context Protocol) server that gives Claude read/write access to Google Docs, Sheets, Drive, and Calendar. Works with Claude Code and Claude Desktop.

24 tools across four services — create, edit, search, and manage your Google Workspace files and events directly from Claude.

## Features

**Google Docs**
- `docs_get` — Read full document content
- `docs_create` — Create a new document
- `docs_append` — Append text to a document
- `docs_replace` — Find and replace text
- `docs_delete` — Move a document to trash

**Google Sheets**
- `sheets_get` — Read cell values from a range
- `sheets_create` — Create a new spreadsheet
- `sheets_update` — Write values to a range
- `sheets_append` — Append rows to a sheet
- `sheets_clear` — Clear a range
- `sheets_delete` — Move a spreadsheet to trash

**Google Drive**
- `drive_list` — List files and folders
- `drive_search` — Search files by name
- `drive_get` — Get file metadata
- `drive_create_folder` — Create a folder
- `drive_move` — Move a file to a different folder
- `drive_delete` — Move a file to trash

**Google Calendar**
- `calendar_list` — List all calendars
- `calendar_events` — List upcoming events
- `calendar_search` — Search events by text
- `calendar_get` — Get full event details
- `calendar_create` — Create a new event
- `calendar_update` — Update an existing event
- `calendar_delete` — Delete an event

## Prerequisites

- Node.js 18 or higher
- A Google Cloud project with OAuth 2.0 credentials

## Setup

### 1. Google Cloud Console

1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Create a new project (or select an existing one)
3. Navigate to **APIs & Services → Credentials**
4. Click **Create Credentials → OAuth Client ID**
5. Choose **Desktop Application** as the application type
6. Download or note the **Client ID** and **Client Secret**

Enable the following APIs for your project:
- [Google Docs API](https://console.cloud.google.com/flows/enableapi?apiid=docs.googleapis.com)
- [Google Drive API](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com)
- [Google Sheets API](https://console.cloud.google.com/flows/enableapi?apiid=sheets.googleapis.com)
- [Google Calendar API](https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com)

### 2. Install and Build

```bash
git clone https://github.com/laltaffer/google-workspace-mcp.git
cd google-workspace-mcp
npm install
npm run build
```

### 3. Register the server

**Claude Code** — one command, user scope so it loads in every project:

```bash
claude mcp add google-workspace --scope user \
  -e GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- node /absolute/path/to/google-workspace-mcp/dist/index.js
```

**Claude Desktop** — add the following to your config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/google-workspace-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Replace `/absolute/path/to/google-workspace-mcp` with the actual path where you cloned the repo.

### 4. Restart the client

Claude Code picks the server up in new sessions. For Claude Desktop, fully quit and reopen it.

### 5. Authorize

In a new Claude chat, say:
> "Call the authorize tool"

Claude will return a Google authorization URL. Open it in your browser, sign in, and grant access. Your browser will show "Authorization complete!" — you only need to do this once. Tokens are saved to `~/.google-workspace-mcp/tokens.json`.

You can now use all Google Workspace tools in Claude.

> **Upgrading?** If you previously authorized without Calendar support, delete `~/.google-workspace-mcp/tokens.json` and re-authorize to grant calendar permissions.

## Usage Examples

> "List my Google Drive files"

> "Create a new Google Doc called 'Meeting Notes' and add an agenda"

> "Read the spreadsheet with ID 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms and summarize it"

> "Find all documents with 'Q1' in the name"

> "Append a new row to my budget spreadsheet: ['March', '4500', 'Rent']"

> "What's on my calendar this week?"

> "Create a meeting called 'Design Review' tomorrow at 2pm for 1 hour"

## Development

```bash
npm test          # run tests
npm run test:watch  # watch mode
npm run build     # compile TypeScript
```

The project uses [vitest](https://vitest.dev/) for testing with mocked googleapis clients. 29 tests across auth, Drive, Docs, Sheets, and Calendar modules.

## Token Storage

OAuth tokens are stored locally at `~/.google-workspace-mcp/tokens.json`. They are never committed to this repository. To revoke access, delete that file or revoke the app in your [Google Account security settings](https://myaccount.google.com/permissions).

## Tech Stack

- [TypeScript](https://www.typescriptlang.org/)
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
- [googleapis](https://github.com/googleapis/google-api-nodejs-client)
- [zod](https://zod.dev/)
- [vitest](https://vitest.dev/)

## License

MIT.