GWS MCP Architecture

MCP server providing 124 tools across 12 Google Workspace services. A single Docker deployment serves 5 authenticated Gmail accounts via FastMCP over Streamable HTTP transport. An nginx auth portal handles OAuth flows and provides a management UI. All traffic is routed through Traefik with dual-domain access (LAN .home and public .sanchezfamily.ca).

Upstream project: Fork of taylorwilsdon/google_workspace_mcp (workspace-mcp v1.9.0, MIT license). Customized with multi-account support, Docker deployment, nginx auth portal, and CLI wrapper (gw).

MCP Tools

124

Google Services

Authenticated Accounts

Containers

Transport

Streamable HTTP

Runtime

Python 3.11 + FastMCP

2. Runtime Architecture

Diagram A: Runtime Request Flow

Request Flow

MCP client (Claude Code, Gemini, etc.) sends a tool invocation via POST /mcp over Streamable HTTP.
Traefik terminates TLS (Let's Encrypt for .sanchezfamily.ca, local CA for .home) and forwards to gws-portal on port 80.
gws-portal (nginx) proxies /mcp, /health, and /oauth2callback to the gws-mcp container on port 8000. Static auth portal UI is served directly.
gws-mcp (FastMCP + FastAPI) resolves the target Google account from tool parameters, loads OAuth credentials from the gws_creds Docker volume, and calls the appropriate Google Workspace API.
Google API responses are marshalled back through the MCP protocol to the calling agent.

Component Classification

Component	Classification	Role
`gws-mcp`	Primary	FastMCP server, 124 tools across 12 Google services
`gws-portal`	Secondary	nginx reverse proxy + OAuth auth portal UI
`gws_creds`	Secondary	Docker volume storing per-account OAuth token JSON files
Traefik	Auxiliary	TLS termination, dual-domain routing (shared infra)
Google Workspace APIs	External	Gmail, Drive, Calendar, Docs, Sheets, Tasks, Contacts, Forms, Slides, Chat, Search, Apps Script
Google OAuth 2.0	External	Token exchange, refresh, consent flow

4. Storage Model

GWS MCP has no database. State is limited to OAuth credential files stored in a named Docker volume.

Store	Type	Mount	Contents
`gws_creds`	Docker volume	`/app/store_creds/`	Per-account OAuth token JSON files (`{email}.json`)

Authenticated Accounts

Email	Role
`[email protected]`	Primary
`[email protected]`	Personal
`[email protected]`	Developer
`[email protected]`	Legal
`[email protected]`	Empiric

Warning: Running docker compose down -v deletes the credentials volume. All 5 accounts would need re-authentication via the portal. Use docker compose down (without -v) to preserve credentials.

5. Public Interfaces (MCP Tools)

HTTP Endpoints

Method	Path	Description
`POST`	`/mcp`	MCP Streamable HTTP endpoint (tool invocation)
`GET`	`/health`	Server health + list of authenticated accounts
`GET`	`/oauth2callback`	OAuth redirect handler
`GET`	`/`	Auth portal UI (glassmorphism setup page)

MCP Client Configuration

// Claude Code
{
  "gws-mcp": {
    "type": "sse",
    "url": "http://gws-mcp.home/mcp"
  }
}

// Other agents (Gemini, Codex, Qwen) via supergateway
{
  "command": "npx",
  "args": ["supergateway", "--streamableHttp", "http://gws-mcp.home/mcp"]
}

Gmail (15 tools)

Tool	Description
`search_gmail_messages`	Search emails with Gmail query syntax
`get_gmail_message_content`	Read full email content by ID
`get_gmail_messages_content_batch`	Batch read multiple emails
`get_gmail_attachment_content`	Download email attachment
`send_gmail_message`	Send email
`draft_gmail_message`	Create email draft
`get_gmail_thread_content`	Read full email thread
`get_gmail_threads_content_batch`	Batch read threads
`list_gmail_labels`	List all labels
`manage_gmail_label`	Create, update, or delete labels
`list_gmail_filters`	List email filters
`create_gmail_filter`	Create email filter
`delete_gmail_filter`	Delete email filter
`modify_gmail_message_labels`	Add/remove labels on a message
`batch_modify_gmail_message_labels`	Bulk label modification

Google Drive (16 tools)

Tool	Description
`search_drive_files`	Search files by name or content
`get_drive_file_content`	Read file content
`get_drive_file_download_url`	Get download URL
`list_drive_items`	List folder contents
`create_drive_file`	Create new file
`import_to_google_doc`	Import file as Google Doc
`get_drive_file_permissions`	List file permissions
`check_drive_file_public_access`	Check public sharing status
`update_drive_file`	Update file content/metadata
`get_drive_shareable_link`	Generate sharing link
`share_drive_file`	Share with users/groups
`batch_share_drive_file`	Batch share with multiple recipients
`update_drive_permission`	Modify sharing permissions
`remove_drive_permission`	Remove sharing access
`copy_drive_file`	Copy file
`transfer_drive_ownership`	Transfer file ownership

Google Calendar (6 tools)

Tool	Description
`list_calendars`	List all calendars
`get_events`	Query calendar events
`create_event`	Create calendar event
`modify_event`	Update event details
`delete_event`	Delete calendar event
`query_freebusy`	Check availability

Google Docs (15 tools)

Tool	Description
`search_docs`	Search documents
`get_doc_content`	Read document content
`list_docs_in_folder`	List docs in Drive folder
`create_doc`	Create new document
`modify_doc_text`	Edit document text
`find_and_replace_doc`	Find and replace in document
`insert_doc_elements`	Insert content elements
`insert_doc_image`	Insert image into document
`update_doc_headers_footers`	Modify headers/footers
`batch_update_doc`	Batch document updates
`inspect_doc_structure`	Inspect document structure
`create_table_with_data`	Insert table with data
`debug_table_structure`	Debug table structure
`export_doc_to_pdf`	Export document as PDF
`update_paragraph_style`	Update paragraph styling

Google Sheets (10 tools)

Tool	Description
`list_spreadsheets`	List spreadsheets
`get_spreadsheet_info`	Get spreadsheet metadata
`read_sheet_values`	Read cell values
`modify_sheet_values`	Write cell values
`format_sheet_range`	Format cell range
`add_conditional_formatting`	Add conditional format rules
`update_conditional_formatting`	Update format rules
`delete_conditional_formatting`	Delete format rules
`create_spreadsheet`	Create new spreadsheet
`create_sheet`	Add sheet tab

Google Tasks (12 tools)

Tool	Description
`list_task_lists`	List task lists
`get_task_list`	Get task list details
`create_task_list`	Create task list
`update_task_list`	Update task list
`delete_task_list`	Delete task list
`list_tasks`	List tasks in a list
`get_task`	Get task details
`create_task`	Create task
`update_task`	Update task
`delete_task`	Delete task
`move_task`	Reorder task
`clear_completed_tasks`	Clear completed tasks

Google Contacts (15 tools)

Tool	Description
`list_contacts`	List contacts
`get_contact`	Get contact details
`search_contacts`	Search contacts
`create_contact`	Create contact
`update_contact`	Update contact
`delete_contact`	Delete contact
`list_contact_groups`	List contact groups
`get_contact_group`	Get group details
`batch_create_contacts`	Batch create contacts
`batch_update_contacts`	Batch update contacts
`batch_delete_contacts`	Batch delete contacts
`create_contact_group`	Create contact group
`update_contact_group`	Update contact group
`delete_contact_group`	Delete contact group
`modify_contact_group_members`	Add/remove group members

Google Forms (6 tools)

Tool	Description
`create_form`	Create form
`get_form`	Get form details
`set_publish_settings`	Configure form publish settings
`get_form_response`	Get individual response
`list_form_responses`	List all form responses
`batch_update_form`	Batch update form structure

Google Slides (5 tools)

Tool	Description
`create_presentation`	Create presentation
`get_presentation`	Get presentation content
`batch_update_presentation`	Batch update slides
`get_page`	Get slide page details
`get_page_thumbnail`	Get slide thumbnail

Google Chat (4 tools)

Tool	Description
`list_spaces`	List chat spaces
`get_messages`	Get messages in a space
`send_message`	Send chat message
`search_messages`	Search chat messages

Google Apps Script (17 tools)

Tool	Description
`list_script_projects`	List script projects
`get_script_project`	Get project metadata
`get_script_content`	Read script source code
`create_script_project`	Create new script project
`update_script_content`	Update script source
`run_script_function`	Execute a script function
`create_deployment`	Deploy script
`list_deployments`	List deployments
`update_deployment`	Update deployment
`delete_deployment`	Delete deployment
`list_script_processes`	List running processes
`delete_script_project`	Delete script project
`list_versions`	List script versions
`create_version`	Create script version
`get_version`	Get version details
`get_script_metrics`	Get execution metrics
`generate_trigger_code`	Generate trigger boilerplate

Google Custom Search (3 tools)

Tool	Description
`search_custom`	Custom search engine query
`get_search_engine_info`	Get search engine config
`search_custom_siterestrict`	Site-restricted search

6. Repository Structure

_gws-mcp/
  docker-compose.yml          # 2 services: gws-mcp + gws-portal
  nginx.conf                  # Reverse proxy config
  README.md                   # Project documentation
  portal/
    index.html                # Glassmorphism OAuth setup UI
  src/
    main.py                   # Entrypoint (CLI + MCP server)
    fastmcp_server.py         # FastMCP Cloud entrypoint
    Dockerfile                # Python 3.11-slim + uv
    pyproject.toml             # workspace-mcp v1.9.0
    auth/
      google_auth.py          # Google OAuth implementation
      credential_store.py     # Per-account token storage
      oauth_config.py         # OAuth config loader
      scopes.py               # Google API scope management
      service_decorator.py    # Auth decorator for tools
      oauth_callback_server.py# Callback handler
      (+ 6 more auth modules)
    core/
      server.py               # FastMCP server setup
      tool_registry.py        # Tool registration + filtering
      tool_tier_loader.py     # Tool tier config (complete/basic)
      tool_tiers.yaml         # Tier definitions
      config.py               # App configuration
      utils.py                # Shared utilities
      (+ 5 more core modules)
    gmail/
      gmail_tools.py          # 15 tools
    gdrive/
      drive_tools.py          # 16 tools
      drive_helpers.py
    gcalendar/
      calendar_tools.py       # 6 tools
    gdocs/
      docs_tools.py           # 15 tools
      docs_helpers.py
      docs_structure.py
      docs_tables.py
      managers/               # Document managers
    gsheets/
      sheets_tools.py         # 10 tools
      sheets_helpers.py
    gtasks/
      tasks_tools.py          # 12 tools
    gcontacts/
      contacts_tools.py       # 15 tools
    gforms/
      forms_tools.py          # 6 tools
    gslides/
      slides_tools.py         # 5 tools
    gchat/
      chat_tools.py           # 4 tools
    gappsscript/
      apps_script_tools.py    # 17 tools
    gsearch/
      search_tools.py         # 3 tools
    tests/                    # pytest test suite
    deploy/                   # Deployment configs

7. Deployment

Container Architecture

Container	Image	Port	Role
`gws-mcp`	Custom (Python 3.11-slim + uv)	8000 (internal)	FastMCP server with 124 tools
`gws-portal`	`nginx:alpine`	80 (internal)	Auth portal UI + reverse proxy to gws-mcp

Docker Network

Both containers run on hosting_web (external Docker bridge shared with Traefik and all hosting services).

Volumes

Volume	Mount	Purpose
`gws_creds`	`/app/store_creds:rw`	OAuth token storage (5 account JSON files)
`./portal`	`/usr/share/nginx/html:ro`	Auth portal static files
`./nginx.conf`	`/etc/nginx/conf.d/default.conf:ro`	nginx reverse proxy config

Traefik Routing

Domain	Target	TLS
`gws-mcp.sanchezfamily.ca`	gws-portal :80	Let's Encrypt (via Cloudflare DNS challenge)
`gws-mcp.home`	gws-portal :80	Local CA wildcard cert

Environment Variables

Variable	Default	Description
`GOOGLE_CLIENT_ID`	(from OAuth project)	Google OAuth 2.0 client ID
`GOOGLE_CLIENT_SECRET`	(from OAuth project)	Google OAuth 2.0 client secret
`GOOGLE_OAUTH_REDIRECT_URI`	`https://gws-mcp.sanchezfamily.ca/oauth2callback`	OAuth callback URL
`WORKSPACE_MCP_PORT`	`8000`	MCP server bind port
`WORKSPACE_MCP_HOST`	`0.0.0.0`	MCP server bind address
`WORKSPACE_MCP_CREDENTIALS_DIR`	`/app/store_creds`	Credential storage directory
`TOOL_TIER`	`complete`	Tool tier (complete or basic)
`OAUTHLIB_INSECURE_TRANSPORT`	`1`	Allow OAuth over HTTP (behind TLS proxy)

Secrets are stored in .env.production at the deploy directory. Google Cloud project ID: 718777906559.

Operations

# Deploy / update
cd /home/rod/_rod/_gws-mcp
docker compose up -d

# Rebuild after code changes
docker compose up -d --build

# View logs
docker compose logs -f gws-mcp
docker compose logs -f gws-portal

# Health check
curl -sk https://gws-mcp.home/health

# Stop (preserves credentials)
docker compose down

Healthcheck

The gws-mcp container has a built-in Docker healthcheck that polls http://localhost:8000/health every 30 seconds (10s timeout, 30s start period, 3 retries). Monitored by Portainer.

8. Dependencies

Python Dependencies

Package	Version	Purpose
`fastmcp`	>=2.14.4	MCP server framework (Streamable HTTP transport)
`fastapi`	>=0.115.12	HTTP API framework (health, OAuth callback)
`google-api-python-client`	>=2.168.0	Google Workspace API client
`google-auth-oauthlib`	>=1.2.2	Google OAuth 2.0 authentication
`google-auth-httplib2`	>=0.2.0	HTTP transport for Google Auth
`httpx`	>=0.28.1	Async HTTP client
`pyjwt`	>=2.10.1	JWT token handling
`cryptography`	>=45.0.0	Cryptographic operations for auth
`python-dotenv`	>=1.1.0	Environment variable loading
`pyyaml`	>=6.0.2	Tool tier config parsing
`py-key-value-aio`	>=0.3.0	Async key-value store

Infrastructure Dependencies

Dependency	Role	Required
Docker + Docker Compose v2	Container runtime	Yes
Traefik (shared)	TLS termination, routing	Yes
Pi-hole DNS (shared)	`.home` domain resolution	For LAN access
Cloudflare (shared)	Public DNS + tunnel	For public access
Google Cloud Console	OAuth app credentials	Yes
`uv`	Python package manager (in container)	Yes (build-time)

Upstream

Forked from taylorwilsdon/google_workspace_mcp (MIT license, v1.9.0). Author: Taylor Wilsdon. Customizations: multi-account support, Docker deployment with nginx portal, CLI wrapper, rod-server integration.

9. Constraints & Risks

Item	Severity	Description
Google OAuth token expiry	Medium	Tokens auto-refresh, but a revoked token requires manual re-auth via the portal. No alerting for expired tokens.
Credential volume deletion	High	`docker compose down -v` destroys all 5 account credentials. No backup mechanism configured.
Google API quotas	Medium	Google Workspace APIs have per-user and per-project rate limits. No client-side rate limiting or retry backoff beyond what the Google client library provides.
OAuth app in "Testing" mode	Low	Google OAuth consent screen is in testing mode, which limits to explicitly listed test users. Production publishing requires Google review.
Single-point proxy	Low	nginx portal is the sole entry point. If it goes down, the MCP server is unreachable even though it may still be healthy.
OAUTHLIB_INSECURE_TRANSPORT=1	Low	Required because Traefik terminates TLS and the container receives HTTP internally. Acceptable in this architecture but would be a concern if the container were directly exposed.

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated — regenerate after significant changes.