Skip to content
Back to search

gws-mcp

Minimal Google Workspace MCP server (Gmail, Calendar, Drive, Contacts). Zero dependencies, tokens stay local.

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vavilovp--gws-mcp/badge.svg)](/listings/vavilovp--gws-mcp)

HTML

<a href="/listings/vavilovp--gws-mcp"><img src="/api/listings/vavilovp--gws-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.

It takes about five minutes. The most important choice is at step 1.

1. Create a Google Cloud project in Personal mode

Open **<https://console.cloud.google.com/auth/overview/personal>** and follow the wizard. It creates a project and a Desktop OAuth client for the single Google account you are signed in with.

> **Use Personal mode, not External + Testing.** An External project in Testing status issues > refresh tokens that expire after **7 days**, so you would have to re-authorize every week. > Personal mode has no verification requirement, no 7-day expiry, no "unverified app" screen > and no 100-user cap. It is limited to the account that created it, which is exactly what a > personal MCP server needs. > > Google Workspace users can instead create an External project with user type **Internal**: > same benefits, limited to the organization.

2. Enable the APIs

Open this link and press **Enable**:

<https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com,calendar-json.googleapis.com,drive.googleapis.com,people.googleapis.com>

If you only plan to use some groups, enable only what you need:

| Group | API | |---|---| | Gmail | `gmail.googleapis.com` | | Calendar | `calendar-json.googleapis.com` | | Drive | `drive.googleapis.com` | | Contacts | `people.googleapis.com` |

3. Download the OAuth client

Go to **<https://console.cloud.google.com/auth/clients>**, open the Desktop client and download the JSON. Then:

mkdir -p ~/.config/gws-mcp
mv ~/Downloads/client_secret_*.json ~/.config/gws-mcp/credentials.json
chmod 600 ~/.config/gws-mcp/credentials.json

4. Authorize

node /path/to/gws-mcp/server.mjs --auth

or, without cloning:

npx github:vavilovp/gws-mcp --auth

A browser opens, you approve the requested scopes, and the token is written to `~/.config/gws-mcp/token.json` with mode `0600`. Check it with:

node /path/to/gws-mcp/server.mjs --status

5. Connect your MCP client

**OpenCode** (`~/.config/opencode/opencode.json`):

{
  "mcp": {
    "servers": {
      "gws": {
        "type": "local",
        "command": ["node", "/path/to/gws-mcp/server.mjs"]
      }
    }
  }
}

**Claude Desktop** (`claude_desktop_config.json`):

{
  "mcpServers": {
    "gws": {
      "command": "npx",
      "args": ["-y", "github:vavilovp/gws-mcp"]
    }
  }
}

Any client that speaks MCP over stdio works: the server reads JSON-RPC lines on stdin and writes them to stdout. Logs go to stderr.

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 · 280 lines
  1. # gws-mcp
  2. A small Google Workspace MCP server for Gmail, Google Calendar, Google Drive and Google Contacts.
  3. One file, zero dependencies, Node 18+. Tokens stay on your machine. Every API call goes
  4. directly from your computer to Google.
  5. ```bash
  6. npx github:vavilovp/gws-mcp --auth
  7. ```
  8. [![CI](https://github.com/vavilovp/gws-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vavilovp/gws-mcp/actions/workflows/ci.yml)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  10. ## Why
  11. Google ships official Gmail and Calendar MCP endpoints, but they are gated behind the
  12. Workspace Developer Preview Program: you have to apply and wait. Hosted aggregators such as
  13. Composio work today, but they hold your OAuth refresh tokens and log tool payloads on their
  14. servers.
  15. This server talks to the regular, generally available Google REST APIs instead. That means:
  16. - no preview application, no vendor account, no third party in the path;
  17. - the OAuth client, refresh token and every request belong to you;
  18. - you can read the entire implementation in one sitting;
  19. - the tool set is deliberately narrow: no permanent deletion, no sharing settings,
  20. no mailbox-wide labels or filters.
  21. ## Tools
  22. | Group | Tool | What it does |
  23. |---|---|---|
  24. | Gmail | `search_threads` | Search threads with Gmail query syntax |
  25. | Gmail | `get_thread` | Read full thread with text bodies |
  26. | Gmail | `create_draft` | Create a draft, nothing is sent |
  27. | Gmail | `send_email` | Send immediately (can be disabled) |
  28. | Calendar | `list_calendars` | List calendars |
  29. | Calendar | `list_events` | List events in a time range |
  30. | Calendar | `create_event` | Create an event, no invitations sent |
  31. | Drive | `search_files` | Search files and folders by name and content |
  32. | Drive | `download_file` | Download or export a file to a local directory |
  33. | Drive | `upload_file` | Upload a local file (secret stores are blocked) |
  34. | Drive | `create_folder` | Create a folder |
  35. | Drive | `move_file` | Move a file or folder |
  36. | Drive | `trash_file` | Move to trash; permanent deletion is not implemented |
  37. | Contacts | `search_contacts` | Search by name, email or phone |
  38. | Contacts | `list_contacts` | List contacts |
  39. ## Requirements
  40. - Node.js 18 or newer
  41. - A Google account
  42. - An OAuth client of type **Desktop app**
  43. ## Setup
  44. It takes about five minutes. The most important choice is at step 1.
  45. ### 1. Create a Google Cloud project in Personal mode
  46. Open **<https://console.cloud.google.com/auth/overview/personal>** and follow the wizard.
  47. It creates a project and a Desktop OAuth client for the single Google account you are signed
  48. in with.
  49. > **Use Personal mode, not External + Testing.** An External project in Testing status issues
  50. > refresh tokens that expire after **7 days**, so you would have to re-authorize every week.
  51. > Personal mode has no verification requirement, no 7-day expiry, no "unverified app" screen
  52. > and no 100-user cap. It is limited to the account that created it, which is exactly what a
  53. > personal MCP server needs.
  54. >
  55. > Google Workspace users can instead create an External project with user type **Internal**:
  56. > same benefits, limited to the organization.
  57. ### 2. Enable the APIs
  58. Open this link and press **Enable**:
  59. <https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com,calendar-json.googleapis.com,drive.googleapis.com,people.googleapis.com>
  60. If you only plan to use some groups, enable only what you need:
  61. | Group | API |
  62. |---|---|
  63. | Gmail | `gmail.googleapis.com` |
  64. | Calendar | `calendar-json.googleapis.com` |
  65. | Drive | `drive.googleapis.com` |
  66. | Contacts | `people.googleapis.com` |
  67. ### 3. Download the OAuth client
  68. Go to **<https://console.cloud.google.com/auth/clients>**, open the Desktop client and
  69. download the JSON. Then:
  70. ```bash
  71. mkdir -p ~/.config/gws-mcp
  72. mv ~/Downloads/client_secret_*.json ~/.config/gws-mcp/credentials.json
  73. chmod 600 ~/.config/gws-mcp/credentials.json
  74. ```
  75. ### 4. Authorize
  76. ```bash
  77. node /path/to/gws-mcp/server.mjs --auth
  78. ```
  79. or, without cloning:
  80. ```bash
  81. npx github:vavilovp/gws-mcp --auth
  82. ```
  83. A browser opens, you approve the requested scopes, and the token is written to
  84. `~/.config/gws-mcp/token.json` with mode `0600`. Check it with:
  85. ```bash
  86. node /path/to/gws-mcp/server.mjs --status
  87. ```
  88. ### 5. Connect your MCP client
  89. **OpenCode** (`~/.config/opencode/opencode.json`):
  90. ```json
  91. {
  92. "mcp": {
  93. "servers": {
  94. "gws": {
  95. "type": "local",
  96. "command": ["node", "/path/to/gws-mcp/server.mjs"]
  97. }
  98. }
  99. }
  100. }
  101. ```
  102. **Claude Desktop** (`claude_desktop_config.json`):
  103. ```json
  104. {
  105. "mcpServers": {
  106. "gws": {
  107. "command": "npx",
  108. "args": ["-y", "github:vavilovp/gws-mcp"]
  109. }
  110. }
  111. }
  112. ```
  113. Any client that speaks MCP over stdio works: the server reads JSON-RPC lines on stdin and
  114. writes them to stdout. Logs go to stderr.
  115. ## Scopes and groups
  116. By default the server requests all four groups:
  117. | Group | Scopes |
  118. |---|---|
  119. | `gmail` | `gmail.readonly`, `gmail.compose` |
  120. | `calendar` | `calendar.calendarlist.readonly`, `calendar.events` |
  121. | `drive` | `drive` (or `drive.file` with `GWS_MCP_DRIVE_SCOPE=file`) |
  122. | `contacts` | `contacts.readonly` |
  123. Choose what you need with `GWS_MCP_GROUPS`:
  124. ```json
  125. {
  126. "mcp": {
  127. "servers": {
  128. "gws": {
  129. "type": "local",
  130. "command": ["node", "/path/to/gws-mcp/server.mjs"],
  131. "env": { "GWS_MCP_GROUPS": "gmail,calendar" }
  132. }
  133. }
  134. }
  135. }
  136. ```
  137. Disabled groups disappear from `tools/list`, so the model cannot call them at all. If the
  138. token was issued earlier, re-run `--auth` after changing groups.
  139. Notes on scope choices:
  140. - `gmail.compose` covers both drafts and sending. To remove sending entirely, either set
  141. `GWS_MCP_ALLOW_SEND=0` or deny the tool in your client.
  142. - `drive` is a **restricted** scope. It is the only way to trash and move arbitrary files.
  143. `GWS_MCP_DRIVE_SCOPE=file` requests `drive.file` instead: non-restricted, but the app then
  144. only sees files it created or that you explicitly opened with it.
  145. - `gmail.readonly`, `gmail.compose` and `drive` are restricted scopes. Using them in your own
  146. Personal-mode project is fine, but a *public* app requesting them would need Google
  147. verification and a yearly CASA security assessment. This is why the project ships as
  148. source code with a per-user OAuth client instead of a shared one.
  149. ## Configuration
  150. | Variable | Default | Meaning |
  151. |---|---|---|
  152. | `GWS_MCP_HOME` | `~/.config/gws-mcp` | Config directory |
  153. | `GWS_MCP_CREDENTIALS` | `$GWS_MCP_HOME/credentials.json` | OAuth client JSON |
  154. | `GWS_MCP_TOKEN` | `$GWS_MCP_HOME/token.json` | Token file |
  155. | `GWS_MCP_PORT` | `43117` | First loopback port to try for the OAuth callback |
  156. | `GWS_MCP_GROUPS` | `gmail,calendar,drive,contacts` | Enabled feature groups |
  157. | `GWS_MCP_DRIVE_SCOPE` | `full` | `full` (`drive`) or `file` (`drive.file`) |
  158. | `GWS_MCP_ALLOW_SEND` | `1` | `0` hides `send_email` |
  159. | `GWS_MCP_DOWNLOAD_DIR` | `~/Downloads/gws-mcp` | Where `download_file` writes |
  160. ## CLI
  161. ```
  162. gws-mcp start the MCP server (stdio)
  163. gws-mcp --auth authorize in a browser and save the token
  164. gws-mcp --status print token path, scopes, groups and expiry
  165. gws-mcp --help usage
  166. ```
  167. ## Security model
  168. **Tokens.** The refresh token is stored locally at `~/.config/gws-mcp/token.json`, mode
  169. `0600`, and is only sent to `oauth2.googleapis.com`. No telemetry, no analytics, no update
  170. checks.
  171. **No third party.** Requests go straight to `gmail.googleapis.com`,
  172. `www.googleapis.com` and `people.googleapis.com`.
  173. **Not implemented on purpose.** There is no `files.delete` (only trashing), no
  174. `permissions.create` (no sharing or changing access), no Gmail settings or filters, no
  175. `users.watch` and no webhook endpoint.
  176. **File system boundaries.** `download_file` writes only inside the configured download
  177. directory. `upload_file` accepts only paths inside your home directory and rejects known
  178. secret stores (`.ssh`, `.aws`, `.config`, `.gnupg`, `.docker`, `.kube`, `.netrc`, `.env*`,
  179. Keychain). This is a speed bump against prompt injection, not a sandbox.
  180. **Prompt injection is the real risk.** Email bodies and documents are untrusted input. A
  181. message can contain instructions that the model may follow, including calling `send_email`
  182. or uploading a file. Mitigations:
  183. - hide the tool: `GWS_MCP_ALLOW_SEND=0`, or add a client-side permission rule
  184. (`{"action": "gws_send_email", "resource": "*", "effect": "deny"}` in OpenCode);
  185. - ask before tools run, if your client supports approvals;
  186. - keep the drive scope at `file` if you do not need to move or trash arbitrary files.
  187. See [SECURITY.md](SECURITY.md) for the full threat model.
  188. ## Troubleshooting
  189. **`invalid_grant: Token has been expired or revoked`** — most often a project in External +
  190. Testing status, where refresh tokens die after 7 days. Move the app to Personal (or Internal
  191. for Workspace) and run `--auth` again. Other causes: you revoked access, changed your Google
  192. password (this revokes Gmail-scoped tokens), or the token went unused for six months.
  193. **`Access blocked: This app's request is invalid` / `redirect_uri_mismatch`** — the OAuth
  194. client is not a Desktop app client. Create a new client of type Desktop app and download its
  195. JSON again.
  196. **`Google API 403: ... API has not been used in project ... or it is disabled`** — enable the
  197. API from step 2, then wait a minute. The message contains a direct link with your project id.
  198. **`Unknown or disabled tool: send_email`** — set by `GWS_MCP_ALLOW_SEND=0`, or the tool is
  199. filtered by your client's permission rules.
  200. **`No token at ...`** — run `--auth` once before starting the server.
  201. **Port already in use** — the server tries ports `43117`-`43136`. Set `GWS_MCP_PORT` to start
  202. elsewhere. Desktop OAuth clients accept any loopback port, so no console change is needed.
  203. ## Development
  204. ```bash
  205. npm run check # node --check server.mjs
  206. npm test # MCP handshake smoke test, no Google account needed
  207. ```
  208. The smoke test spawns the server, performs `initialize` and `tools/list`, and checks the tool
  209. list. It never calls Google.
  210. ## License
  211. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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