Skip to content
Back to search

google-workspace-mcp

A Model Context Protocol (MCP) server that provides authenticated access to Google Workspace APIs, offering integrated Authentication, Gmail, Calendar, and Drive functionality

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aaronsb--google-workspace-mcp/badge.svg)](/listings/aaronsb--google-workspace-mcp)

HTML

<a href="/listings/aaronsb--google-workspace-mcp"><img src="/api/listings/aaronsb--google-workspace-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

First, you need **Google OAuth credentials** — the one prerequisite common to every path:

1. Go to [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) 2. Create an **OAuth 2.0 Client ID**, application type **Desktop app** 3. Enable the APIs you want (Gmail, Calendar, Drive, Sheets, Docs, Tasks, Meet — and **People API** for contacts, which is what Google calls it in the console) 4. Keep the **Client ID** and **Client Secret** handy — you'll paste them in below

Then pick the path that matches how you work. All three run the same server.

Node 22.12 or newer. (Node 18 and 20 are both end-of-life.)

---

📦 → 🤖 Claude Desktop — one-click `.mcpb` install (recommended)

Download **`google-workspace-mcp.mcpb`** from the [latest release](https://github.com/aaronsb/google-workspace-mcp/releases/latest), then **drag it onto the Claude Desktop window**, or double-click it.

Claude Desktop opens an install dialog with three fields:

| Field | | |---|---| | **Google OAuth Client ID** | required — from the step above | | **Google OAuth Client Secret** | required — from the step above | | **Workspace Directory** | optional — where attachments, downloads and exports land. Defaults to `~/.local/share/google-workspace-mcp/workspace/`. Give it a dedicated folder — not your home, Documents, Desktop, or a Google Drive folder. |

Paste, hit Save, done. No JSON to edit, no Node to install, no paths to get right — the bundle carries the server and every dependency.

**One bundle covers every platform** — macOS (Intel and Apple Silicon), Linux (x64 and ARM64), and Windows. There is nothing to choose: the server is pure JavaScript, so there is no platform-specific payload to pick between.

> *Cross-platform note:* `.mcpb` files install via Claude Desktop's bundled handler. If double-clicking doesn't trigger Claude on your system, drag the file onto the Claude Desktop window instead, or right-click → "Open with…" and pick Claude Desktop (then "always open with" if your OS offers). Behavior varies: macOS usually auto-associates, Windows may need a one-time association, Linux varies by desktop environment.

---

Claude Code — one command

claude mcp add google-workspace \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- npx -y @aaronsb/google-workspace-mcp

That's it — no file to edit. Verify with `/mcp`.

---

Other MCP clients

Add an entry to the client's MCP config file (for Claude Desktop by hand, that's `claude_desktop_config.json`; for Claude Code, `.mcp.json`):

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@aaronsb/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Or install it globally and point at the binary directly:

npm install -g @aaronsb/google-workspace-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 303 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Google Workspace MCP Server
  2. [![npm version](https://img.shields.io/npm/v/@aaronsb/google-workspace-mcp?logo=npm&label=npm)](https://www.npmjs.com/package/@aaronsb/google-workspace-mcp)
  3. [![Latest release](https://img.shields.io/github/v/release/aaronsb/google-workspace-mcp?include_prereleases&label=release)](https://github.com/aaronsb/google-workspace-mcp/releases)
  4. [![Node](https://img.shields.io/node/v/@aaronsb/google-workspace-mcp?logo=node.js&label=node)](https://nodejs.org)
  5. [![License](https://img.shields.io/github/license/aaronsb/google-workspace-mcp)](LICENSE)
  6. **Give your AI agent real access to Google Workspace** — Gmail, Calendar, Drive, Docs, Sheets, Tasks, Meet and Contacts — from one MCP server, across as many accounts as you have.
  7. Search your mail, check your calendar, write a doc, file a task — in conversation, as yourself.
  8. ## Install
  9. First, you need **Google OAuth credentials** — the one prerequisite common to every path:
  10. 1. Go to [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
  11. 2. Create an **OAuth 2.0 Client ID**, application type **Desktop app**
  12. 3. Enable the APIs you want (Gmail, Calendar, Drive, Sheets, Docs, Tasks, Meet — and **People API** for contacts, which is what Google calls it in the console)
  13. 4. Keep the **Client ID** and **Client Secret** handy — you'll paste them in below
  14. Then pick the path that matches how you work. All three run the same server.
  15. Node 22.12 or newer. (Node 18 and 20 are both end-of-life.)
  16. ---
  17. ### 📦 → 🤖 Claude Desktop — one-click `.mcpb` install (recommended)
  18. Download **`google-workspace-mcp.mcpb`** from the [latest release](https://github.com/aaronsb/google-workspace-mcp/releases/latest), then **drag it onto the Claude Desktop window**, or double-click it.
  19. Claude Desktop opens an install dialog with three fields:
  20. | Field | |
  21. |---|---|
  22. | **Google OAuth Client ID** | required — from the step above |
  23. | **Google OAuth Client Secret** | required — from the step above |
  24. | **Workspace Directory** | optional — where attachments, downloads and exports land. Defaults to `~/.local/share/google-workspace-mcp/workspace/`. Give it a dedicated folder — not your home, Documents, Desktop, or a Google Drive folder. |
  25. Paste, hit Save, done. No JSON to edit, no Node to install, no paths to get right — the bundle carries the server and every dependency.
  26. **One bundle covers every platform** — macOS (Intel and Apple Silicon), Linux (x64 and ARM64), and Windows. There is nothing to choose: the server is pure JavaScript, so there is no platform-specific payload to pick between.
  27. > *Cross-platform note:* `.mcpb` files install via Claude Desktop's bundled handler. If double-clicking doesn't trigger Claude on your system, drag the file onto the Claude Desktop window instead, or right-click → "Open with…" and pick Claude Desktop (then "always open with" if your OS offers). Behavior varies: macOS usually auto-associates, Windows may need a one-time association, Linux varies by desktop environment.
  28. ---
  29. ### Claude Code — one command
  30. ```bash
  31. claude mcp add google-workspace \
  32. -e GOOGLE_CLIENT_ID=your-client-id \
  33. -e GOOGLE_CLIENT_SECRET=your-client-secret \
  34. -- npx -y @aaronsb/google-workspace-mcp
  35. ```
  36. That's it — no file to edit. Verify with `/mcp`.
  37. ---
  38. ### Other MCP clients
  39. Add an entry to the client's MCP config file (for Claude Desktop by hand, that's `claude_desktop_config.json`; for Claude Code, `.mcp.json`):
  40. ```json
  41. {
  42. "mcpServers": {
  43. "google-workspace": {
  44. "command": "npx",
  45. "args": ["-y", "@aaronsb/google-workspace-mcp"],
  46. "env": {
  47. "GOOGLE_CLIENT_ID": "your-client-id",
  48. "GOOGLE_CLIENT_SECRET": "your-client-secret"
  49. }
  50. }
  51. }
  52. }
  53. ```
  54. Or install it globally and point at the binary directly:
  55. ```bash
  56. npm install -g @aaronsb/google-workspace-mcp
  57. ```
  58. ## How it fits together
  59. ```mermaid
  60. flowchart LR
  61. human["🧑 You<br>ask in plain language"]
  62. agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
  63. server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
  64. keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
  65. google["☁️ Google<br>Gmail · Calendar · Drive · Docs<br>Sheets · Tasks · Meet · Contacts"]
  66. human -->|"“what's on my calendar?”"| agent
  67. agent -->|"tool call"| server
  68. server <-->|"which account?"| keys
  69. server -->|"real API call, as you"| google
  70. google -->|"your data"| server
  71. server -->|"shaped for an agent<br>+ what to do next"| agent
  72. agent -->|"an answer"| human
  73. classDef person fill:#475569,color:#ffffff,stroke:#94a3b8
  74. classDef robot fill:#2d7d9a,color:#ffffff,stroke:#4a5568
  75. classDef ours fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
  76. classDef secrets fill:#2d8e5e,color:#ffffff,stroke:#4a5568
  77. classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706
  78. class human person
  79. class agent robot
  80. class server ours
  81. class keys secrets
  82. class google external
  83. ```
  84. **Your credentials never leave your machine.** The server holds an OAuth token per account, on your own disk, and calls Google *as you* — there is no middleman service, no account of ours, nothing to sign up for. Add as many accounts as you like (personal and work, side by side); the server routes each request to the right one.
  85. ## What it can do
  86. **12 tools across 8 Google services**, plus multi-account handling, per-account read-only access, bulk execution, content authoring, and a file sandbox.
  87. | Tool | What It Does |
  88. |------|--------------|
  89. | `manage_email` | Gmail — search, read (plain or sanitized HTML), send, reply / reply-all, forward, triage, trash, drafts (list / delete), labels, threads, attachments |
  90. | `manage_calendar` | Calendar — list, agenda, get, create, quickAdd (natural language), update, delete, calendars, freebusy |
  91. | `manage_drive` | Drive — search, get, upload, download, copy, rename / move, delete, export, permissions, comments, view images |
  92. | `manage_sheets` | Sheets — read / write ranges (row-numbered output), append, clear, manage tabs, copy / duplicate / rename |
  93. | `manage_docs` | Docs — get, create, append, insert text, find-and-replace |
  94. | `manage_tasks` | Tasks — list / create / update / complete tasks and task lists |
  95. | `manage_meet` | Meet — create and configure meeting spaces, see who is in a call now, browse past conferences, participants, transcripts, recordings, smart notes |
  96. | `manage_contacts` | Contacts — look people up in your saved contacts, the addresses you have only corresponded with, and your organization's directory; create, update and delete contacts |
  97. | `manage_accounts` | Multi-account lifecycle — add accounts, manage credentials and scopes |
  98. | `manage_scratchpad` | Compose / edit multi-line content (line- or JSON-path-addressed), attach files, send to any target; JSON mode live-syncs to Docs / Sheets |
  99. | `manage_workspace` | File operations in the workspace sandbox (exchange point for attachments, downloads, exports) |
  100. | `bulk_operations` | Do many things in one call — chain different operations in sequence with `$N.field` references, or apply one operation to many resources in a single Google request (`queue_operations` still works as an alias) |
  101. Every response carries **next-steps** guidance, so the agent always knows what it can do next.
  102. ## One ask, many steps
  103. The useful part isn't any single operation — it's that your agent can **string them together**.
  104. You ask for one thing. The agent works out that it needs four API calls, in order, each one feeding the next:
  105. ```mermaid
  106. sequenceDiagram
  107. autonumber
  108. participant H as 🧑 You
  109. participant A as 🤖 Your agent
  110. participant S as ⚙️ MCP server
  111. participant G as ☁️ Google
  112. H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
  113. A->>S: find the email
  114. S->>G: search Gmail
  115. G-->>S: the message
  116. S-->>A: found it — and here's what you can do next
  117. A->>S: save the attachment
  118. S->>G: download it
  119. A->>S: put it in Drive
  120. S->>G: upload
  121. A->>S: create a task, due Friday
  122. S->>G: Google Tasks
  123. A-->>H: Done. Invoice filed, task set for Friday.
  124. ```
  125. Two things make this work. Every response tells the agent **what it can do next**, so it isn't guessing at the next step. And `bulk_operations` lets it run a whole chain in **one call**, feeding each result into the next — so "find the invoice, file it, remind me" is a single round trip rather than four.
  126. When the work is *the same* operation over many things, it can go further and use one Google request for all of them:
  127. ```
  128. bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
  129. items: ['msg1', 'msg2', 'msg3', … ] }
  130. ```
  131. Two hundred messages trashed in one round trip instead of two hundred. This is narrow on purpose — it works only where Google publishes a method for it, which today is contacts (create, update, delete, get) and Gmail (trash, label changes). Ask for it anywhere else and the answer names the operations that can, and points you back at sequential mode, which works everywhere.
  132. ## Ask for what's missing
  133. This server exposes **95 operations**, reaching 79 of the **257 methods** Google publishes across those eight APIs. It is a curated subset on purpose: an agent has to *choose* among these, and every method it must weigh is one it can pick wrongly. A tool with 257 operations isn't more capable than one with 95 — it's harder to use correctly.
  134. But that judgement was made without you.
  135. **→ [Browse every method Google publishes](docs/api-surface.md)**
  136. Every method is listed — what it does, whether we expose it, and a **Request** link that opens a pre-filled issue. The descriptions are Google's own, quoted verbatim, and the page is generated from the same specification the client is built from, so it can't drift from reality.
  137. That page also lists **three whole APIs this server doesn't touch yet** — Chat, Slides and Forms — for the same reason: *not targeted* is a decision, not a fact of nature.
  138. A good request **names the task, not the method**:
  139. > *"I want the agent to file incoming invoices into a folder automatically."*
  140. That can be evaluated. It might turn out an existing operation already does it, or that the right answer is a different method than the one you found. *"Expose `users.settings.filters.create`"* is a conclusion, not a case — lead with the problem and let the method follow.
  141. ## Why Apache 2.0, and not open core
  142. **Everything is here.** There is no paid tier, no "enterprise" build, no feature held back to sell you later. What you install is what exists.
  143. Open core works by keeping the good part back. The free thing is a lead magnet, and the moment your use gets serious you discover the operation you need lives behind a licence. That model would be especially rotten *here*: this is a piece of plumbing between you and **your own data**, using **your own Google credentials**, running on **your own machine**. Nothing about that arrangement should have a paywall in the middle of it, and nothing about it needs a vendor.
  144. [Apache 2.0](LICENSE) rather than MIT for two concrete reasons:
  145. - **An explicit patent grant.** Contributors licence their patent claims along with their code, so using this can't become a patent problem later. MIT is silent on patents, which means the question is merely unanswered rather than settled.
  146. - **It's safe to adopt at work.** Apache 2.0 is on essentially every corporate allow-list. Fork it, vendor it, ship it inside a commercial product — you don't owe anyone anything, and you don't need to ask.
  147. The one obligation is attribution: keep the notices ([`NOTICE`](NOTICE), [`LICENSE`](LICENSE)) with the code. That's it.
  148. Through v3.0.0 this project was MIT-licensed, and that history is preserved rather than erased — MIT-era contributions keep their original notice in [`LICENSE-MIT`](LICENSE-MIT), and their authors are credited in [`NOTICE`](NOTICE). Apache 2.0 takes back nothing MIT permitted.
  149. ## Usage
  150. Add an account (opens a browser for OAuth):
  151. ```
  152. manage_accounts { "operation": "authenticate" }
  153. ```
  154. Then use any tool with your account email:
  155. ```
  156. manage_email { "operation": "triage", "email": "you@gmail.com" }
  157. manage_calendar { "operation": "agenda", "email": "you@gmail.com" }
  158. manage_drive { "operation": "search", "email": "you@gmail.com", "query": "quarterly report" }
  159. ```
  160. ### Give an account read-only access
  161. Some accounts should never be written to. Ask for less at consent time and the **token itself** cannot send, edit or delete — this isn't a rule layered over a broad token:
  162. ```
  163. manage_accounts { "operation": "scopes", "email": "you@gmail.com",
  164. "services": "gmail,drive,contacts", "access": "read" }
  165. ```
  166. Google is asked for the read-only variant of each scope, so ticking every box on the consent screen still yields a read-only token. `manage_accounts status` reports what each account actually holds.
  167. A write from a read-only account is refused before the request leaves, with the account, the operation, and the way back:
  168. ```
  169. 'create' needs write access to contacts. Account you@gmail.com was authorized
  170. read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
  171. email:'you@gmail.com', services:'contacts', access:'readwrite'}, or use an
  172. account that already has it.
  173. ```
  174. Where a service has no read-only scope, you're told which ones and what they'll still be able to do **before** the browser opens.
  175. ### Multi-step workflows
  176. Chain operations with result references — the output of one step feeds the next:
  177. ```json
  178. {
  179. "operations": [
  180. { "tool": "manage_email", "args": { "operation": "search", "email": "you@gmail.com", "query": "from:boss subject:review" }},
  181. { "tool": "manage_email", "args": { "operation": "read", "email": "you@gmail.com", "messageId": "$0.messageId" }}
  182. ]
  183. }
  184. ```
  185. ### One operation, many things
  186. Where Google publishes a method for it, the same operation across many resources costs one request:
  187. ```json
  188. {
  189. "mode": "batch",
  190. "tool": "manage_contacts",
  191. "operation": "delete",
  192. "email": "you@gmail.com",
  193. "items": ["people/c1", "people/c2", "people/c3"]
  194. }
  195. ```
  196. Anything shared by the whole batch goes at the top level; `items` carry only what differs — a bare id is enough when that's all it is.
  197. ## Where your data lives
  198. Follows the XDG Base Directory Specification:
  199. | Data | Location |
  200. |------|----------|
  201. | Account registry | `~/.config/google-workspace-mcp/accounts.json` |
  202. | Credentials | `~/.local/share/google-workspace-mcp/credentials/` |
  203. | Workspace (file exchange) | `~/.local/share/google-workspace-mcp/workspace/` |
  204. Credentials are per-account files holding standard OAuth tokens. No secrets are stored in the project directory.
  205. ## Under the hood
  206. You don't need any of this to use the server. But if you're curious, or you want to add an operation:
  207. The server builds its Google API client **from Google's own machine-readable API specifications**. Nothing is transcribed by hand, so the surface can't drift from reality, and adding an operation is a YAML edit rather than a code change.
  208. - **[How it works](docs/how-it-works.md)** — the build-time / runtime split, the descriptor, the factory
  209. - **[API coverage](docs/coverage.md)** — what's exposed, what isn't, and how to ask for more
  210. - **[The full API surface](docs/api-surface.md)** — every method Google publishes, plus the three APIs we don't target yet
  211. - **[Architecture decisions](docs/architecture/)** — the ADRs, including why this server owns its Google client outright
  212. ## License
  213. [Apache License 2.0](LICENSE) — see [Why Apache 2.0](#why-apache-20-and-not-open-core) above.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.