{
  "markdown": "# Google Workspace MCP Server\n\nMCP server providing Claude access to Google Drive, Docs, Sheets, Slides, Calendar, Gmail, and Contacts.\n\nFork of `@dguido/google-workspace-mcp` with added support for:\n\n- **Multi-workspace**: Serve multiple Google accounts from a single process, selected by URL path (`/mcp/personal`, `/mcp/business`)\n- **Email attachments**: Send and receive file attachments via Gmail\n- **Workspace signatures**: Auto-append plain text and HTML signatures per workspace\n- **Sender display name**: Auto-inject `From` header with display name from workspace config\n\n## Quick Start\n\n### 1. Set Up Google Cloud\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com) and create or select a project\n2. [Enable all required APIs](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com,docs.googleapis.com,sheets.googleapis.com,slides.googleapis.com,calendar-json.googleapis.com,gmail.googleapis.com,people.googleapis.com) (one-click link)\n3. Go to [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials) and create an OAuth 2.0 Client ID (Desktop app type)\n4. Copy the **Client ID** and **Client Secret**\n\n### 2. Configure Claude Desktop\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"google-workspace\": {\n      \"command\": \"npx\",\n      \"args\": [\"@danielrosehill/google-workspace-mcp\"],\n      \"env\": {\n        \"GOOGLE_CLIENT_ID\": \"YOUR_CLIENT_ID.apps.googleusercontent.com\",\n        \"GOOGLE_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\",\n        \"GOOGLE_WORKSPACE_SERVICES\": \"drive,gmail,calendar\"\n      }\n    }\n  }\n}\n```\n\nThat's it. On first tool call, a browser window opens for Google OAuth consent. Tokens are saved automatically.\n\n<details>\n<summary>Alternative: file-based credentials</summary>\n\nDownload the credentials JSON from Google Cloud Console and save to `~/.config/google-workspace-mcp/credentials.json`, then authenticate manually:\n\n```bash\nnpx @dguido/google-workspace-mcp auth\n```\n\nSee [Advanced Configuration](docs/ADVANCED.md) for file-based setup, named profiles, and multi-account setup.\n\n</details>\n\n## What You Can Do\n\n```\nCreate a Google Doc called \"Project Plan\" in /Work/Projects with an outline for Q1.\n```\n\n```\nSearch for files containing \"budget\" and organize them into the Finance folder.\n```\n\n```\nCreate a presentation called \"Product Roadmap\" with slides for Q1 milestones.\n```\n\n## Google Cloud Setup\n\n### 1. Create a Google Cloud Project\n\n- Go to the [Google Cloud Console](https://console.cloud.google.com)\n- Click \"Select a project\" > \"New Project\"\n- Name your project (e.g., \"Google Drive MCP\")\n\n### 2. Enable Required APIs\n\n- [Enable all APIs at once](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com,docs.googleapis.com,sheets.googleapis.com,slides.googleapis.com,calendar-json.googleapis.com,gmail.googleapis.com,people.googleapis.com) (one-click link)\n- Or manually: Go to \"APIs & Services\" > \"Library\" and enable: **Google Drive API**, **Google Docs API**, **Google Sheets API**, **Google Slides API**, **Google Calendar API**, **Gmail API**, **People API**\n\n### 3. Configure OAuth Consent Screen\n\n- Go to \"APIs & Services\" > \"OAuth consent screen\"\n- Fill in app name, support email, and developer contact\n- Choose \"External\" (or \"Internal\" for Workspace)\n- Add your email as a test user\n- Add scopes: `drive.file`, `documents`, `spreadsheets`, `presentations`, `drive`, `drive.readonly`, `calendar`, `gmail.modify`, `gmail.labels`, `contacts`\n\n### 4. Create OAuth 2.0 Credentials\n\n- Go to \"APIs & Services\" > \"Credentials\"\n- Click \"+ CREATE CREDENTIALS\" > \"OAuth client ID\"\n- Application type: **Desktop app**\n- Copy the **Client ID** and **Client Secret** (or download the JSON file)\n\n## Configuration\n\n### File Locations\n\nBoth credentials and tokens are stored in `~/.config/google-workspace-mcp/` by default:\n\n| File              | Default Path                                      |\n| ----------------- | ------------------------------------------------- |\n| OAuth credentials | `~/.config/google-workspace-mcp/credentials.json` |\n| Auth tokens       | `~/.config/google-workspace-mcp/tokens.json`      |\n\n### Environment Variables\n\n| Variable                          | Description                                                   |\n| --------------------------------- | ------------------------------------------------------------- |\n| `GOOGLE_CLIENT_ID`                | OAuth Client ID (simplest setup — no credentials file needed) |\n| `GOOGLE_CLIENT_SECRET`            | OAuth Client Secret (used with `GOOGLE_CLIENT_ID`)            |\n| `GOOGLE_WORKSPACE_MCP_TOKEN_PATH` | Custom token storage location                                 |\n| `GOOGLE_WORKSPACE_MCP_PROFILE`    | Named profile for credential isolation                        |\n| `GOOGLE_WORKSPACE_SERVICES`       | Comma-separated list of services to enable                    |\n\n### Token-Efficient Output (TOON)\n\nFor LLM-optimized responses that reduce token usage by 20-50%, enable TOON format:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-workspace\": {\n      \"command\": \"npx\",\n      \"args\": [\"@danielrosehill/google-workspace-mcp\"],\n      \"env\": {\n        \"GOOGLE_WORKSPACE_SERVICES\": \"drive,gmail,calendar\",\n        \"GOOGLE_WORKSPACE_TOON_FORMAT\": \"true\"\n      }\n    }\n  }\n}\n```\n\nTOON (Token-Oriented Object Notation) encodes structured responses more compactly than JSON by eliminating repeated field names. Savings are highest for list operations (calendars, events, emails, filters).\n\n### Service Configuration\n\nBy default, we recommend enabling only the core services (`drive,gmail,calendar`) as shown in Quick Start. This provides file management, email, and calendar capabilities without the complexity of document editing tools.\n\nTo enable additional services, add them to `GOOGLE_WORKSPACE_SERVICES`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-workspace\": {\n      \"command\": \"npx\",\n      \"args\": [\"@danielrosehill/google-workspace-mcp\"],\n      \"env\": {\n        \"GOOGLE_WORKSPACE_SERVICES\": \"drive,gmail,calendar,docs,sheets,slides\"\n      }\n    }\n  }\n}\n```\n\n**Available services:** `drive`, `docs`, `sheets`, `slides`, `calendar`, `gmail`, `contacts`\n\n- Omit `GOOGLE_WORKSPACE_SERVICES` entirely to enable all services\n- Unified tools (`create_file`, `update_file`, `get_file_content`) require `drive`, `docs`, `sheets`, and `slides`\n- When you limit services, only the OAuth scopes for those services are requested during authentication. If you change enabled services, re-authenticate to update granted scopes.\n\nSee [Advanced Configuration](docs/ADVANCED.md) for named profiles, multi-account setup, and environment variables.\n\n### Multi-Workspace Mode\n\nServe multiple Google accounts from a single process. Create a `workspaces.json`:\n\n```json\n{\n  \"personal\": {\n    \"email\": \"you@gmail.com\",\n    \"senderName\": \"Your Name\",\n    \"signature\": \"Your Name\\nhttps://yoursite.com\",\n    \"signatureHtml\": \"<b>Your Name</b><br><a href=\\\"https://yoursite.com\\\">yoursite.com</a>\",\n    \"clientCredentials\": \"/path/to/personal/client.json\",\n    \"tokenPath\": \"/path/to/personal/token.json\"\n  },\n  \"business\": {\n    \"email\": \"you@company.com\",\n    \"senderName\": \"Your Name\",\n    \"signature\": \"Your Name\\nCompany — https://company.com\",\n    \"signatureHtml\": \"<b>Your Name</b><br><a href=\\\"https://company.com\\\">Company</a>\",\n    \"clientCredentials\": \"/path/to/business/client.json\",\n    \"tokenPath\": \"/path/to/business/token.json\"\n  }\n}\n```\n\nStart the server with HTTP transport:\n\n```bash\nGWS_WORKSPACES_CONFIG=/path/to/workspaces.json \\\nGWS_MCP_PORT=3200 \\\nGWS_MCP_HOST=0.0.0.0 \\\nnpx @danielrosehill/google-workspace-mcp start\n```\n\nConnect clients to workspace-specific URLs:\n\n- `http://host:3200/mcp/personal` — routes to the personal workspace\n- `http://host:3200/mcp/business` — routes to the business workspace\n\nEach workspace gets its own OAuth tokens, sender name, and signature. The `workspace` parameter is auto-injected from the URL path — clients don't need to include it in tool calls.\n\n#### Workspace Config Fields\n\n| Field               | Required | Description                                                |\n| ------------------- | -------- | ---------------------------------------------------------- |\n| `email`             | yes      | Google account email                                       |\n| `clientCredentials` | yes      | Path to OAuth `client.json`                                |\n| `tokenPath`         | yes      | Path to store OAuth tokens                                 |\n| `label`             | no       | Display label (defaults to workspace name)                 |\n| `senderName`        | no       | Display name for outgoing emails (e.g., \"Daniel Rosehill\") |\n| `signature`         | no       | Plain text signature auto-appended to email body           |\n| `signatureHtml`     | no       | HTML signature auto-appended to email HTML part            |\n\n### Email Attachments\n\nSend emails with file attachments:\n\n```\nSend an email to user@example.com with subject \"Report\" and attach the Q1 report PDF.\n```\n\nAttachments are passed as base64-encoded content with filename and MIME type. The server also supports downloading attachments from received emails via the `download_attachment` tool.\n\n## Available Tools\n\n### Drive (29 tools)\n\n`search` `listFolder` `createFolder` `createTextFile` `updateTextFile` `deleteItem` `renameItem` `moveItem` `copyFile` `getFileMetadata` `exportFile` `shareFile` `getSharing` `removePermission` `listRevisions` `restoreRevision` `downloadFile` `uploadFile` `getStorageQuota` `starFile` `resolveFilePath` `batchDelete` `batchRestore` `batchMove` `batchShare` `listTrash` `restoreFromTrash` `emptyTrash` `getFolderTree`\n\n### Google Docs (8 tools)\n\n`createGoogleDoc` `updateGoogleDoc` `getGoogleDocContent` `appendToDoc` `insertTextInDoc` `deleteTextInDoc` `replaceTextInDoc` `formatGoogleDocRange`\n\n### Google Sheets (7 tools)\n\n`createGoogleSheet` `updateGoogleSheet` `getGoogleSheetContent` `formatGoogleSheetCells` `mergeGoogleSheetCells` `addGoogleSheetConditionalFormat` `sheetTabs`\n\n### Google Slides (10 tools)\n\n`createGoogleSlides` `updateGoogleSlides` `getGoogleSlidesContent` `formatSlidesText` `formatSlidesShape` `formatSlideBackground` `createGoogleSlidesTextBox` `createGoogleSlidesShape` `slidesSpeakerNotes` `listSlidePages`\n\n### Calendar (7 tools)\n\n`listCalendars` `listEvents` `getEvent` `createEvent` `updateEvent` `deleteEvent` `findFreeTime`\n\n### Gmail (14 tools)\n\n`sendEmail` `draftEmail` `readEmail` `searchEmails` `deleteEmail` `modifyEmail` `downloadAttachment` `listLabels` `getOrCreateLabel` `updateLabel` `deleteLabel` `createFilter` `listFilters` `deleteFilter`\n\n### Contacts (6 tools)\n\n`listContacts` `getContact` `searchContacts` `createContact` `updateContact` `deleteContact`\n\n### Unified (3 tools)\n\n`createFile` `updateFile` `getFileContent`\n\n[Full API Reference](docs/API.md)\n\n## Troubleshooting\n\n### \"OAuth credentials not found\"\n\nSet `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` env vars in your MCP config, or save your credentials file to `~/.config/google-workspace-mcp/credentials.json`.\n\n### \"Authentication failed\" or browser doesn't open\n\nEnsure credential type is \"Desktop app\" (not \"Web application\"). The server uses an ephemeral port assigned by the OS, so no specific ports need to be available.\n\n### \"Tokens expired\" or \"Invalid grant\"\n\nApps in \"Testing\" status expire tokens after 7 days. Re-authenticate:\n\n```bash\nrm ~/.config/google-workspace-mcp/tokens.json\nnpx @dguido/google-workspace-mcp auth\n```\n\n**To avoid weekly re-authentication:** Publish your OAuth app (see [Avoiding Token Expiry](#avoiding-token-expiry) below).\n\n### \"API not enabled\"\n\nEnable the missing API in [Google Cloud Console](https://console.cloud.google.com) > APIs & Services > Library.\n\n### \"Login Required\" even with valid tokens\n\nRevoke app access at [Google Account Permissions](https://myaccount.google.com/permissions), clear tokens, and re-authenticate.\n\n[Full Troubleshooting Guide](docs/TROUBLESHOOTING.md)\n\n## Security\n\n- RFC 8252-compliant OAuth 2.0 with PKCE (Proof Key for Code Exchange)\n- Loopback-only authentication server (127.0.0.1)\n- State parameter for CSRF protection\n- Automatic token refresh\n- Tokens stored with 0600 permissions\n- All processing happens locally\n- Never commit credentials or tokens to version control\n\n## Avoiding Token Expiry\n\nOAuth apps in \"Testing\" status automatically expire tokens after 7 days. To avoid weekly re-authentication:\n\n### Option 1: Publish Your OAuth App (Recommended)\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com) > APIs & Services > OAuth consent screen\n2. Click \"PUBLISH APP\"\n3. For personal use, you don't need to complete Google's verification process\n4. Published apps keep tokens valid until explicitly revoked\n\n**Note:** Publishing makes your app available to any Google user, but since you control the OAuth credentials, only you can authenticate.\n\n### Option 2: Use Internal App (Workspace Only)\n\nIf you have a Google Workspace account:\n\n1. Set User Type to \"Internal\" on the OAuth consent screen\n2. Internal apps don't expire tokens and don't require publishing\n\n### Monitoring Token Age\n\nUse `get_status` to check token age. Tokens older than 6 days show a warning automatically.\n\n## Development\n\n```bash\nnpm install\nnpm run build    # Compile TypeScript\nnpm run check    # typecheck + lint + format check\nnpm test         # Run tests\n```\n\nSee [Contributing Guide](CONTRIBUTING.md) for project structure and development workflow.\n\n## Origin\n\nThis project is a substantial rewrite of [piotr-agier/google-drive-mcp](https://github.com/piotr-agier/google-drive-mcp), originally created by Piotr Agier.\n\n## License\n\nMIT - See LICENSE file for details.\n",
  "bytes": 13864,
  "sha": "4400eb9c863bd03623f6b2fe9735f7edf83db92cbb691eb18e1aecf6e46bd933",
  "repo_slug": "danielrosehill/google-workspace-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_danielrosehill_google_workspace_mcp_05f2972a/readme"
}