gws-mcp-server

<div align="center">

# gws-mcp-server

Google Workspace for AI agents: Gmail, Calendar, Drive, Sheets, Docs, and Tasks as a curated set of 39 [Model Context Protocol](https://modelcontextprotocol.io/) tools, built on the official [Google Workspace CLI (`gws`)](https://github.com/googleworkspace/cli).

[![npm version](https://img.shields.io/npm/v/gws-mcp-server?style=flat-square)](https://www.npmjs.com/package/gws-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Node](https://img.shields.io/badge/Node-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
[![Podcast](https://img.shields.io/badge/Podcast-Chain_of_Thought-purple?style=flat-square)](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=gws-mcp-server)
[![X](https://img.shields.io/badge/X-@ConorBronsdon-black?style=flat-square&logo=x)](https://x.com/ConorBronsdon)

<img src="docs/demo.gif" alt="Demo: an agent calls the calendar_events_list tool and gets events back (sample data)" width="800">

</div>

---


## Why?

The `gws` CLI had a built-in MCP server that was [removed in v0.8.0](https://github.com/googleworkspace/cli/pull/275) because it exposed 200-400 tools — causing context window bloat in MCP clients. This server takes a curated approach: you choose which Google services to expose, and only a focused set of high-value, narrowly scoped operations are registered as tools. Every tool declares all four MCP annotation hints — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` — so clients can reason about side effects, know which writes are safe to retry, and surface clearer consent prompts.

## Prerequisites

- [Node.js](https://nodejs.org/) 18+
- [`gws` CLI](https://github.com/googleworkspace/cli) installed and authenticated (`npm install -g @googleworkspace/cli && gws auth login`)



### Grant fewer scopes than the default



This server exposes **no send tool** — the closest thing is `gmail_drafts_create`, which explicitly does not send. The token `gws auth login` mints is broader than that.



`gws auth login` opens a scope picker listing **nine** scopes. The default grant is **seven**: full read-write `drive`, `spreadsheets`, `gmail.modify` (Google documents it as "Read, compose, and send emails"), `calendar`, `documents`, `presentations`, and `tasks` — the same seven you get running non-interactively as `DEFAULT_SCOPES`.

The other two rows are Cloud Pub/Sub and Cloud Platform, and neither is part of the default grant — `gws auth login --help` describes `--full` as "Request all scopes incl. pubsub + cloud-platform."

Which rows start *checked* has not been verified against a live picker — the seven above are the documented default grant, not an observation of the TUI. Read the checkboxes before pressing Enter rather than trusting this paragraph.



So the token on disk can send mail and rewrite Drive even though nothing here will. **Deselect what you do not need in the picker**, or:



```bash

gws auth login --readonly    # read-only across services

```



`-s gmail` limits the picker to Gmail, per the flag's own help text ("Comma-separated service names to limit scope picker"). It cannot pull in `cloud-platform` or `pubsub`, because those two are reachable only through `--full`.



**On Linux there is no keyring, and the encryption key is a file next to the data it encrypts.** `gws` enables the `keyring` crate's native backends only for macOS and Windows; on every other platform the dependency is declared with no backend feature, so the store falls through to writing `.encryption_key` into `~/.config/gws/`. That file is not a backup of a key held elsewhere — it is the key, and the credential store's own doc comment says it is never deleted. Setting `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file` changes nothing there because that is already the only path. On macOS and Windows the key file is removed once the OS keyring holds the key. **If you run this headless on Linux, treat `~/.config/gws/` as a password file: anyone who can read the directory has the credentials.**

## Quick start

```bash
# Install
npm install -g gws-mcp-server

# Or run from source
git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm install && npm run build
```

## Configuration

### Claude Code (`.mcp.json`)

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar,docs,gmail,tasks"
      ]
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar"
      ]
    }
  }
}
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--services, -s` | Comma-separated list of services to expose | All services |
| `--gws-path` | Path to the `gws` binary | `gws` |
| `--read-only` | Register only the read-only tools | off |

### `--read-only`

`--read-only` registers **17 tools** instead of 39. Every tool that writes to Google is left unregistered, so it never appears in `tools/list` and there is nothing for an agent to call — including `gmail_drafts_create`, which is a write even though it never sends. `drive_files_download` stays, since it reads.

```bash
gws-mcp-server --read-only
gws-mcp-server --read-only --services drive,calendar   # combines with -s
```

This constrains the **agent, not the credential**. The token on disk keeps whatever scopes it was granted, and anything else on the machine can still use it. `gws auth login --readonly` is what narrows the token; the two are complementary. For an MCP server the agent is the threat model, but that is the limit of the claim.

## Available services & tools

### `drive` (9 tools)
- `drive_files_list` — Search and list files
- `drive_files_get` — Get file metadata
- `drive_files_create` — Create files (with optional upload)
- `drive_files_copy` — Copy files (useful for format conversion)
- `drive_files_update` — Update file metadata/content
- `drive_files_delete` — Delete files
- `drive_files_export` — Export Google Workspace files (Doc, Sheet, Slide) to other formats
- `drive_files_download` — Download file content (text inline, binary as base64 or saved to a path; Google-native files are exported to a readable format)
- `drive_permissions_create` — Share files

### `sheets` (4 tools)
- `sheets_get` — Get spreadsheet metadata
- `sheets_values_get` — Read cell values
- `sheets_values_update` — Write cell values
- `sheets_values_append` — Append rows

### `calendar` (5 tools)
- `calendar_events_list` — List events
- `calendar_events_get` — Get event details
- `calendar_events_insert` — Create events
- `calendar_events_update` — Update events (only supplied fields change)
- `calendar_events_delete` — Delete events

### `docs` (3 tools)
- `docs_get` — Get document content
- `docs_create` — Create documents
- `docs_batchUpdate` — Apply document updates

### `gmail` (6 tools)
- `gmail_messages_list` — Search messages
- `gmail_messages_get` — Read a message
- `gmail_threads_list` — Search threads
- `gmail_threads_get` — Read a full thread
- `gmail_threads_modify` — Add/remove labels on a thread (archive, mark read, star)
- `gmail_drafts_create` — Create a draft (plain text and/or HTML, with reply threading via `threadId`). Drafts are never auto-sent

### `tasks` (12 tools)
- `tasks_tasklists_list` — List task lists
- `tasks_tasklists_get` — Get a task list
- `tasks_tasklists_insert` — Create a task list
- `tasks_tasklists_update` — Update a task list (only supplied fields change)
- `tasks_tasklists_delete` — Delete a task list
- `tasks_tasks_list` — List tasks (filters: completed/hidden/due dates)
- `tasks_tasks_get` — Get a task
- `tasks_tasks_insert` — Create a task (optionally nested or positioned)
- `tasks_tasks_update` — Update a task (only supplied fields change; common use: mark complete)
- `tasks_tasks_move` — Move a task within/across lists or reorder
- `tasks_tasks_delete` — Delete a task
- `tasks_tasks_clear` — Hide all completed tasks in a list

> **Update semantics:** the `*_update` tools (calendar events, tasks, task lists) use the Google API's `patch` verb — they merge the fields you supply and leave the rest untouched. To *clear* an existing value, pass it explicitly (e.g. an empty string) rather than omitting it.

**Total: 39 tools** (vs 200-400 in the old implementation)

## Adding new tools

Edit `src/services.ts` to add tool definitions. Each tool maps directly to a `gws` CLI command:

```typescript
{
  name: "drive_files_list",           // MCP tool name
  description: "List files in Drive", // Shown to AI
  command: ["drive", "files", "list"],// gws CLI args
  params: [                           // Maps to --params JSON
    { name: "q", description: "Search query", type: "string", required: false },
  ],
  bodyParams: [                       // Maps to --json body
    { name: "name", description: "File name", type: "string", required: true },
  ],
}
```

### Typed errors

Tool call failures are mapped to a typed error hierarchy (`src/errors.ts`): `AuthenticationError` (401/403), `RateLimitError` (429), `ValidationError` (400), `NotFoundError` (404, with a shared-drive access hint for `drive` commands), and `ServerError` (5xx), all extending a base `GwsError`. Unlike an HTTP API client, this server has no response object to read a status code from — it spawns the `gws` CLI as a subprocess and only sees plain text (stdout/stderr, or a rejected promise's `.message`). `mapGwsErrorToTyped()` recovers a status-like code from that text, han