Google Workspace

You run an MCP server that lets Claude Code interact with Google Workspace services like Gmail, Drive, Sheets, Docs, and Calendar. It exposes a set of well-defined tools you can call from Claude Code to perform actions on Google services in a secure and auditable way.

How to use

After you start the Google Workspace MCP server, you connect your MCP client to it using a local stdio configuration. You can call a suite of tools to search, read, modify, create, and delete Google Workspace resources. Each tool is exposed under a clear name such as gmail_search_messages, drive_upload_file, calendar_create_event, and so on. You enable and disable capabilities via environment variables and follow safe-by-default settings to prevent unintended actions.

How to install

Prerequisites: you need Node.js and a compatible package manager installed on your machine. You will also need pnpm in order to install dependencies and build the project.

Step 1: Install dependencies

cd company-mcp
pnpm install

Step 2: Build the server

pnpm build

Step 3: Prepare environment variables and credentials

cd apps/mcp-server-google
cp .env.example .env
# Edit .env to enable proper features and credentials

Step 4: Start the MCP server (stdio mode) using the runtime command shown below

{
  "type": "stdio",
  "name": "google",
  "command": "node",
  "args": ["/path/to/company-mcp/apps/mcp-server-google/dist/index.js"],
  "env": {
    "AUTH_MODE": "oauth",
    "OAUTH_TOKEN_PATH": "/path/to/company-mcp/.secrets/token.json",
    "GMAIL_SEND_ENABLED": "true"
  }
}

Configuration and security

Security is built in with explicit enablement flags for actions that can modify data. By default, destructive or high-risk operations are disabled. You explicitly enable them in the environment configuration, then restart the server.

Important flags and defaults you should know are:

GMAIL_SEND_ENABLED         false
GMAIL_DELETE_ENABLED       false
GMAIL_MODIFY_LABELS_ENABLED false
DRIVE_MODIFY_ENABLED       false
DRIVE_DELETE_ENABLED       false
CALENDAR_MODIFY_ENABLED    false
CALENDAR_DRY_RUN_DEFAULT false

Troubleshooting

If you encounter authentication issues, re-authenticate to refresh tokens. If a token is expired, remove the existing token and re-run the OAuth flow.

Common errors and steps to resolve them:

• No OAuth token found: run pnpm auth:oauth to authenticate.

• Token has expired: remove .secrets/token.json and re-authenticate with pnpm auth:oauth.

• Folder not in allowlist: add folder IDs to DRIVE_ALLOWLIST_FOLDERS in your environment configuration.

Development

Common development tasks include building, type checking, linting, and tests.

pnpm build
pnpm typecheck
pnpm lint
pnpm test

Directory layout overview

The project is organized with a dedicated MCP server for Google Workspace under apps/mcp-server-google, a core utility library, skills, and documentation. Key components include authentication modules, tool implementations for Gmail/Drive/Sheets/Docs/Calendar, and a dist entry point for the MCP server.

Available tools

gmail_search_messages

Search Gmail messages by query and return a list of results.

gmail_get_message

Retrieve details of a single Gmail message.

gmail_list_labels

List Gmail labels for the authenticated user.

gmail_modify_labels

Modify labels on Gmail messages or threads.

gmail_send_message

Send a Gmail message.

gmail_reply_message

Reply to a Gmail message.

gmail_delete_message

Delete a Gmail message.

gmail_create_draft

Create a new Gmail draft.

gmail_get_attachment

Download an attachment from a Gmail message.

drive_search_files

Search files in Google Drive.

drive_get_file

Get metadata for a Drive file.

drive_create_folder

Create a new folder in Drive.

drive_set_permission

Set sharing permissions on Drive files/folders.

drive_copy_file

Copy a Drive file.

drive_upload_file

Upload a file to Drive.

drive_download_file

Download a Drive file.

drive_delete_file

Delete a Drive file.

drive_move_file

Move a Drive file.

sheets_create_spreadsheet

Create a new Google Sheets spreadsheet.

sheets_get_values

Read values from a range in Sheets.

sheets_update_values

Update values in a Sheets range.

sheets_append_values

Append values to a Sheets range.

sheets_batch_get_values

Batch retrieve values from multiple ranges.

sheets_batch_update_values

Batch update values across ranges.

sheets_add_sheet

Add a new sheet to a spreadsheet.

sheets_delete_sheet

Delete a sheet from a spreadsheet.

sheets_format_cells

Format cells in a sheet.

docs_create_document

Create a new Google Docs document.

docs_get_document

Retrieve a Google Docs document.

docs_insert_text

Insert text into a Docs document.

docs_replace_text

Replace text in a Docs document.

docs_format_text

Format text in a Docs document.

docs_insert_image

Insert an image into a Docs document.

docs_batch_update

Perform batch updates on a Docs document.

calendar_list_events

List calendar events.

calendar_create_event

Create a calendar event (dry-run supported).

calendar_update_event

Update a calendar event (dry-run supported).

calendar_delete_event

Delete a calendar event.

calendar_get_free_busy

Check free/busy information on calendars.