Worksuite MCP

Connect Claude (or any MCP client) to your Google Workspace. Worksuite MCP is a polished, batteries-included Model Context Protocol 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 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 (provides uvx). Install it with:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• A Google account
• An MCP client. These instructions use Claude Code, but any MCP client works.

---

Step 1 - Get the code

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 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:

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

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

Then check it:

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 by Taylor Wilsdon and contributors. Licensed under the MIT License (see LICENSE).