Gws Connector

GWS Connector

Multi-account Google Workspace MCP server — connect multiple Gmail, Google Calendar, and Google Drive accounts with smart routing.

Works with Claude Code, Gemini CLI, GitHub Copilot, Cursor, OpenAI Codex, and any MCP-compatible client.

Why

Most AI coding assistants support a single Google account. If you use multiple Google accounts (personal + work, multiple clients, different orgs), you need to switch between them manually. This MCP server lets you connect them all at once and route requests by label, email, or domain.

Features

• Multi-account — connect unlimited Gmail and Google Workspace accounts
• Smart routing — target accounts by label (work), email, or domain
• Per-account OAuth — different orgs can use their own GCP credentials
• Secure storage — client secrets and tokens stored in OS keychain (file fallback on Linux without GNOME Keyring)
• 49 tools — Mail (11), Calendar (7), Drive (3), Sheets (8), Docs (4), Contacts (2), Tasks (5), Slides (3), account management (6)
• Account management — add, remove, set default, list accounts
• Cross-platform — standard MCP server works with any compatible client

How it compares

There are several good Google Workspace MCP servers. GWS Connector is the one to pick when multiple accounts and operational simplicity matter:

If you only ever use a single Google account and want the widest possible tool surface (Forms, Chat, Vault, …), a single-account server like taylorwilsdon/google_workspace_mcp may fit better. GWS Connector focuses on doing multi-account Gmail / Calendar / Drive / Sheets / Docs / Contacts / Tasks / Slides cleanly and securely.

Upgrading (Google Tasks)

The Google Tasks tools (gws.tasks.*) are added behind one new OAuth scope (tasks). Existing users must re-authorize each connected account so new tokens are minted with this scope:

/gws:reauth

Before approving the browser consent screen, review what the new scope grants — full read and write access to the account's Google Tasks lists and tasks. See the scope rationale table below for details.

You must also add the tasks scope and enable the Tasks API in your GCP project's OAuth consent screen configuration before re-auth, or the consent screen will reject the request. Until an account is re-authorized, the gws.tasks.* tools return an insufficient-scope error naming the reauth tool to run.

Upgrading — Contacts / People API

The Contacts tools (gws.contacts.search, gws.contacts.directory_search) add two new read-only OAuth scopes (contacts.readonly, directory.readonly). Existing users must re-authorize each connected account so new tokens are minted with these scopes:

/gws:reauth

Before approving the browser consent screen, review what the new scopes grant — read-only access to your Google Contacts and (for Workspace accounts) the organization directory. See the scope rationale table below for details.

You must also enable the People API and add the two new scopes in your GCP project's OAuth consent screen configuration before re-auth, or the consent screen will reject the request. gws.contacts.directory_search requires a Google Workspace account — personal Gmail accounts have no organization directory and receive a clear explanatory message instead of results.

Upgrading (Google Slides tools)

The Slides tools (gws.slides.*) add one new OAuth scope, https://www.googleapis.com/auth/presentations. Existing users must re-authorize each connected account so new tokens are minted with the Slides scope:

/gws:reauth

You must also enable the Slides API and add the presentations scope in your GCP project's OAuth consent screen configuration before re-auth, or the consent screen will reject the request (see Google Cloud Setup). Until you re-authorize, gws.slides.* calls return a scope error telling the agent to run gws.accounts.reauth; all other tools keep working.

Upgrading from v0.2.x

v0.3.0 adds native Google Sheets and Google Docs tools behind two new OAuth scopes (spreadsheets, documents). Existing users must re-authorize each connected account so new tokens are minted with these scopes:

/gws:reauth

Before approving the browser consent screen, review what the new scopes grant — full read and write access to every spreadsheet and document in that account's Google Drive, including files shared with the account. See the scope rationale table below for details.

You must also add the two new scopes (and enable the Sheets and Docs APIs) in your GCP project's OAuth consent screen configuration before re-auth, or the consent screen will reject the request.

Quick Start (Claude Code)

1. Install the plugin — run these two commands inside Claude Code:

/plugin marketplace add orieg/gws-connector

/plugin install gws@gws-connector

2. Set up Google Cloud credentials — the interactive wizard walks you through everything:

/gws:configure

This creates a GCP project, enables APIs, and connects your first account. See Google Cloud Setup if you prefer manual steps.

3. Connect additional accounts:

/gws:add-account

Each account can use different OAuth credentials from different GCP projects.

Gemini CLI

gemini extensions install https://github.com/orieg/gws-connector

The binary is downloaded automatically on first use. Then connect accounts inside Gemini:

gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")

Other clients

GitHub Copilot / Cursor / Codex / Any MCP client

Download a prebuilt binary or build from source:

git clone https://github.com/orieg/gws-connector && cd gws-connector && make build

Then configure your client:

Connect accounts via MCP tool call:

gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")

Environment variables (all optional): GWS_GOOGLE_CLIENT_ID, GWS_GOOGLE_CLIENT_SECRET, GWS_STATE_DIR

The --use-dot-names flag uses gws.mail.search naming; without it, tools use gws_mail_search.

Local development / testing

git clone https://github.com/orieg/gws-connector

cd gws-connector make build claude --plugin-dir ./

Use /reload-plugins inside the session after making changes. Run claude --debug --plugin-dir ./ to troubleshoot plugin loading.

Claude Desktop / MCPB bundle

Each release attaches a one-click `gws-mcp.mcpb` bundle. Download it and open it with Claude Desktop (Settings → Extensions → install from file), or drag it in. The bundle contains the binaries for macOS and Linux and picks the right one for your machine automatically. You still complete the Google Cloud setup and connect accounts on first use.

The server is also published to the official MCP Registry as io.github.orieg/gws-connector, so MCP clients that browse the registry can find and install it directly.

Docker

A multi-arch image is published to GHCR on each release:

docker run -i --rm ghcr.io/orieg/gws-connector:latest

The server speaks MCP over stdio. Interactive OAuth (accounts.add / reauth) opens a browser and stores secrets in the OS keychain, so it needs host access — day-to-day use is best via the native binary, the Claude Code plugin, or the Gemini extension. The image is well suited to headless stdio integrations and to registry/introspection checks. Persist the account registry across runs by mounting a volume and pointing GWS_STATE_DIR at it:

docker run -i --rm -v gws-state:/state -e GWS_STATE_DIR=/state \

ghcr.io/orieg/gws-connector:latest

Usage

All gws.* tools accept an optional account parameter:

# Uses default account

gws.mail.search(q: "is:unread")

Target by label

gws.cal.list_events(account: "work")

Target by email

gws.drive.search(account: "alice@company.com", q: "quarterly report")

Available tools

| gws.sheets.read_range | Read a single A