# Worksuite MCP

**Connect Claude (or any MCP client) to your Google Workspace.** Worksuite MCP
is a polished, batteries-included [Model Context Protocol](https://modelcontextprotocol.io)
server that gives your AI assistant full access to **Gmail, Google Drive, Docs,
Sheets, Slides, Calendar, Forms, Tasks, Chat and Contacts**, all through your own
Google account and your own OAuth app. Your data stays yours.

It wraps the excellent open-source
[`workspace-mcp`](https://pypi.org/project/workspace-mcp/) engine and adds a clean
launcher, a self-healing startup, and the setup guide below so you can be talking
to your inbox and Drive in a few minutes.

---

## What you can do once it is connected

- **Gmail** - search, read, draft, send, and label email.
- **Drive** - search files, read content, upload, share, and manage folders.
- **Docs / Sheets / Slides** - create and edit documents, read and write cells, build decks.
- **Calendar** - read your schedule, create and move events, check free/busy.
- **Tasks, Forms, Chat, Contacts** - full read/write across the rest of Workspace.

Around 120 tools in total. You talk to your AI in plain language ("find the
invoice from Acme and forward it to finance") and it uses these tools to do it.

---

## Requirements

- macOS or Linux
- [`uv`](https://docs.astral.sh/uv/) (provides `uvx`). Install it with:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- A Google account
- An MCP client. These instructions use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but any MCP client works.

---

## Step 1 - Get the code

```bash
git clone https://github.com/chadvdwww-hash/worksuite-mcp.git
cd worksuite-mcp
chmod +x bin/worksuite-mcp.sh
```

## Step 2 - Create your Google OAuth app

Worksuite MCP signs in as *you*, using *your own* Google Cloud OAuth client. You
create it once. It takes about five minutes.

1. Open the [Google Cloud Console](https://console.cloud.google.com/) and create
   (or pick) a project.
2. **Enable the APIs** you want under *APIs & Services → Library*. At minimum
   enable: Gmail API, Google Drive API, Google Docs API, Google Sheets API,
   Google Slides API, Google Calendar API. (Enable Tasks, Forms, Chat and People
   APIs too if you want those tools.)
3. Go to *APIs & Services → OAuth consent screen*:
   - User type: **External**.
   - Fill in the app name (e.g. "Worksuite MCP") and your email.
   - Under **Test users**, add the Google account you will sign in with. This is
     required while the app is in *Testing* mode, or Google blocks the login with
     `403 access_denied`.
4. Go to *APIs & Services → Credentials → Create credentials → OAuth client ID*:
   - Application type: **Desktop app** (or **Web application**).
   - If you pick Web application, add this authorized redirect URI:
     `http://localhost:8000/oauth2callback`
   - Download the client secret JSON.

> **Heads up on token lifetime:** while your OAuth app is in *Testing* mode,
> Google expires the refresh token after **7 days**, so you re-authenticate
> roughly weekly. Publish the app (*OAuth consent screen → Publish app*) to make
> it permanent.

## Step 3 - Point Worksuite MCP at your credentials

Tell the server where your downloaded client secret lives:

```bash
export GOOGLE_CLIENT_SECRET_PATH="/absolute/path/to/your/client_secret.json"
```

(You can also set `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET`
directly instead of a file. Either way, keep these secret. They are gitignored.)

## Step 4 - Register it with Claude Code

```bash
claude mcp add worksuite-mcp -- /absolute/path/to/worksuite-mcp/bin/worksuite-mcp.sh
```

Then check it:

```bash
claude mcp list
# worksuite-mcp: .../bin/worksuite-mcp.sh - ✔ Connected
```

## Step 5 - Sign in to Google (first run)

The first time your AI calls a Workspace tool, Worksuite MCP opens a Google
sign-in page in your browser. Approve the scopes (you may see an "unverified app"
warning because it is *your* personal app; click through to continue). After that
your credentials are cached and reused automatically.

That's it. Ask your assistant to "list my recent Drive files" or "summarise my
unread email" to confirm it works.

---

## Good to know (saves you an hour)

- **Port 8000 must be free.** The OAuth sign-in flow listens on `localhost:8000`
  (it can roam up to 8004). The launcher auto-reaps stale Worksuite/Workspace
  instances holding those ports before each start, so a crashed session won't
  block the next one. If sign-in still fails with "port in use", something else
  is on 8000: `lsof -nP -iTCP:8000 -sTCP:LISTEN`.
- **File uploads are sandboxed.** Tools that import a local file only read from
  `~/.workspace-mcp/attachments/` by default. Either copy the file there first,
  or set `ALLOWED_FILE_DIRS=/your/dir` and restart the server.
- **Avoid dots in new document titles.** When creating a Doc from a file, a name
  like `Cal.com Setup` gets truncated to `Cal`. Use `Cal-com Setup` and rename
  afterward if needed.
- **Where credentials live.** Once you sign in, tokens are stored under
  `~/.google_workspace_mcp/credentials/`. Delete that file to force a fresh login.

---

## How it works

Worksuite MCP is a thin wrapper. It pins the upstream `workspace-mcp` package,
applies its own branding and startup banner, runs a port-reaper so a crashed run
never blocks the next, then hands off to the upstream server which does the
Google API heavy lifting. Upgrading the engine is a one-line version bump in
`pyproject.toml`.

```
your AI client  <-- MCP -->  Worksuite MCP launcher  -->  Google Workspace APIs
```

## Credits

Built on [`workspace-mcp`](https://pypi.org/project/workspace-mcp/) by Taylor
Wilsdon and contributors. Licensed under the MIT License (see `LICENSE`).