# How It Works The Mailworks MCP Server connects Claude to Google Workspace. When someone uses Claude and asks it to read a Google Doc, search Drive, or update a spreadsheet, this server is the bridge that makes that happen. It runs on AWS, handles authentication securely, and routes requests to the right Google API. The server is a private fork of an open-source project ([`taylorwilsdon/google_workspace_mcp`](https://github.com/taylorwilsdon/google_workspace_mcp)) maintained at `themailworks/mcp-google`. We added audit logging to Splunk, persistent credential storage, and the full AWS infrastructure. *** ## How the Pieces Connect ``` Claude --> Mailworks MCP Server --> Google APIs (AWS / Fargate) (Docs, Drive, Sheets) | |-- ElastiCache (stores login sessions) |-- Secrets Manager (stores passwords and keys) '-- Splunk Cloud (logs who did what) ``` All traffic is encrypted over HTTPS. The server lives inside a private AWS network with no direct public exposure beyond the load balancer. *** ## What's Currently Enabled The server has three Google Workspace services turned on: **Google Docs**, **Google Drive**, and **Google Sheets**. Additional services (Gmail, Calendar, Slides, Forms, Tasks, Chat, Contacts, Apps Script, Custom Search) are available but disabled. See `Future Tools (Not Yet Enabled)` for the full list. *** ## Tool Reference These are the 45 tools Claude can use right now. Each one maps to a specific Google API action. ### Google Docs (19 tools) | Tool | What It Does | | ---------------------------- | ---------------------------------------------------------------------------------------------- | | `create_doc` | Creates a new Google Doc with optional initial text. | | `get_doc_content` | Gets the plain text content of a Google Doc or a .docx file stored in Drive. | | `get_doc_as_markdown` | Reads a Google Doc and returns it as Markdown, optionally including comments. | | `batch_update_doc` | Runs multiple operations on a Doc at once (insert text, format, find/replace, tables). | | `find_and_replace_doc` | Finds and replaces text throughout a Doc. | | `inspect_doc_structure` | Returns the Doc's internal structure: element indices, table positions, safe insertion points. | | `modify_doc_text` | Inserts or replaces text and applies formatting. | | `update_paragraph_style` | Applies paragraph-level formatting: headings, alignment, spacing, list styles. | | `insert_doc_elements` | Inserts tables, lists, or page breaks. | | `insert_doc_image` | Inserts an image from a Drive file or a public URL. | | `create_table_with_data` | Creates a table and fills it with data in one step. | | `debug_table_structure` | Inspects an existing table's dimensions, cell positions, and content. | | `update_doc_headers_footers` | Creates or updates header and footer text. | | `export_doc_to_pdf` | Exports a Doc to PDF and saves it to Drive. | | `import_to_google_doc` | Imports a file (Markdown, DOCX, TXT, HTML, RTF, ODT) into native Google Docs format. | | `list_docs_in_folder` | Lists all Google Docs in a specific Drive folder. | | `search_docs` | Searches for Google Docs by name. | | `list_document_comments` | Lists all comments on a Doc. | | `manage_document_comment` | Creates, replies to, or resolves a comment on a Doc. | ### Google Sheets (13 tools) | Tool | What It Does | | ------------------------------- | ---------------------------------------------------------------------------- | | `create_spreadsheet` | Creates a new spreadsheet with optional named sheets. | | `get_spreadsheet_info` | Returns spreadsheet metadata: title, locale, sheet list. | | `create_sheet` | Adds a new sheet tab to an existing spreadsheet. | | `read_sheet_values` | Reads values from a specified cell range. | | `modify_sheet_values` | Writes, updates, or clears values in a cell range. | | `format_sheet_range` | Applies formatting: colors, fonts, alignment, number formats, text wrapping. | | `resize_sheet_dimensions` | Resizes, freezes, hides, inserts, or deletes rows and columns. | | `manage_conditional_formatting` | Adds, updates, or deletes conditional formatting rules. | | `append_table_rows` | Appends rows to a structured table. | | `list_sheet_tables` | Lists all structured tables with their IDs, ranges, and columns. | | `list_spreadsheets` | Lists spreadsheets the user has access to. | | `list_spreadsheet_comments` | Lists all comments on a spreadsheet. | | `manage_spreadsheet_comment` | Creates, replies to, or resolves a comment on a spreadsheet. | ### Google Drive (13 tools) | Tool | What It Does | | -------------------------------- | ------------------------------------------------------------------------------- | | `create_drive_file` | Creates a new file in Drive, optionally with content or from a URL. | | `create_drive_folder` | Creates a new folder, including inside shared drives. | | `copy_drive_file` | Copies an existing file with an optional new name and location. | | `update_drive_file` | Updates a file's metadata and properties. | | `search_drive_files` | Searches for files and folders across Drive, including shared drives. | | `list_drive_items` | Lists files and folders in a specific folder. | | `get_drive_file_content` | Gets the text content of a file (Docs, Sheets, Slides, Office files, etc.). | | `get_drive_file_download_url` | Downloads a file or returns a temporary download link. | | `get_drive_file_permissions` | Gets detailed metadata about a file including its sharing permissions. | | `get_drive_shareable_link` | Returns the shareable link and current sharing status for a file or folder. | | `set_drive_file_permissions` | Controls link sharing settings and file-level sharing behavior. | | `manage_drive_access` | Grants, revokes, updates, or batch-manages permissions and ownership transfers. | | `check_drive_file_public_access` | Checks whether a file has public link sharing turned on. | *** ## Tool Tiers The server uses a tiering system to control how many tools are exposed. We currently run on `complete`, which enables all 45 tools listed above. The three tiers are: | Tier | What It Includes | | ---------- | ------------------------------------------------------------------------------------------------------ | | `core` | The essentials: search, read, create, and basic editing across all enabled services. | | `extended` | Everything in core, plus management tools like labels, folders, batch operations, and advanced search. | | `complete` | Everything. Comments, headers/footers, publishing settings, admin functions. | Each tier includes everything from the tier below it. The tier definitions live in `core/tool_tiers.yaml` in the application repository. *** ## Turning Tools On and Off The server reads two settings to decide what to expose: * `TOOL_TIER` (currently `complete`): controls how many tools per service are available. * `TOOLS` (currently `"drive docs sheets"`): controls which Google services are active. Both are environment variables set in the Terraform configuration. The current values: ```hcl environment_vars = { MCP_ENABLE_OAUTH21 = "true" TOOL_TIER = "complete" WORKSPACE_EXTERNAL_URL = "https://google.mcp.themailworks.com" RESTRICTED_FOLDER_NAMES = "Restricted - AI,PII- HR Employee Files" TOOLS = "drive docs sheets" } ``` ### To enable a new service (e.g., Calendar) 1. Make sure the Google API is enabled in the GCP project first (see the Permissions page, Section: GCP Project Details). 2. Open `variables.tf`, find the `google_workspace` block inside `var.mcp_services`. 3. Add the service name to the `TOOLS` string: ```hcl TOOLS = "drive docs sheets calendar" ``` 4. Run `terraform plan` and confirm only the task definition changes. 5. Run `terraform apply`. The server automatically restarts with the new tools. 6. Verify at `https://google.mcp.themailworks.com/mcp` that the new tools appear. **Heads up:** If the new service requires new Google permissions, users will be asked to re-authorize the next time they use Claude. This happens automatically. ### To disable a service 1. Remove the service name from the `TOOLS` string. 2. Run `terraform apply`. 3. Optionally flush user sessions in Redis if you want to revoke the permissions immediately (see the Troubleshoot page for Redis commands). This forces everyone to log in again. ### To change the tool tier Change `TOOL_TIER` to `core`, `extended`, or `complete` and apply. The effective tool set is the overlap of the tier and the `TOOLS` list. ### Restricting folders from AI access `RESTRICTED_FOLDER_NAMES` is a comma-separated list of Google Drive folder names the server will refuse to open, regardless of tool. Add or remove names and apply: ```hcl RESTRICTED_FOLDER_NAMES = "Restricted - AI,PII- HR Employee Files,Legal Hold" ``` *** ## Quick Reference | Item | Value | | ------------------- | ----------------------------------------------------------- | | Server URL | | | Health Check | | | AWS Account | 573946584375 | | Region | us-east-1 | | ECS Cluster | prod-mcp-cluster | | Service Name | prod-mcp-google-workspace | | Container Logs | /ecs/prod/mcp/google\_workspace | | Terraform State | s3://573946584375-mcp-terraform-state/mcp/terraform.tfstate | | Google OAuth Secret | /prod/mcp/google-oauth | | Splunk Secret | /prod/mcp/splunk | | Alarm SNS Topic | arn:aws:sns:us-east-1:573946584375:MCPAlerts | | Splunk Audit Index | mcp\_audit | | ECR Repository | 573946584375.dkr.ecr.us-east-1.amazonaws.com/mcp/workspace | | GitHub Repo (app) | themailworks/mcp-google | | GitHub Repo (infra) | themailworks/mcp-terraform | | GCP Project | CUSTOM-MCP-SERVER-MAILWORKS | | GCP Project Owner | | | Base Domain | mcp.themailworks.com | | ALB | prod-mcp-alb | | Upstream Fork | taylorwilsdon/google\_workspace\_mcp | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://knowledge.themailworks.com/mcp-server/how-it-works.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.