Skip to main content
Glama
google-workspace-mcp
by hoaaah

google-workspace-mcp

Verified by M8ven

A local MCP server that provides access to Google Drive, Sheets, Docs, Calendar, and Gmail via OAuth2. Compatible with any MCP client (Claude Desktop, Continued, or other AI agents). Runs as a local process (stdio).

Available Tools

Service

Tools

Drive

drive_search_files, drive_get_file_metadata, drive_read_file_content, drive_upload_file, drive_create_folder, drive_download_file, drive_trash_file

Sheets

sheets_read_range, sheets_write_range, sheets_append_values, sheets_clear_range, sheets_create_spreadsheet, sheets_list_tabs

Docs

docs_create_document, docs_read_document, docs_append_text, docs_replace_text

Calendar

calendar_list_calendars, calendar_list_events, calendar_create_event, calendar_update_event, calendar_delete_event

Gmail

gmail_search_messages, gmail_get_message, gmail_send_message, gmail_create_draft, gmail_list_labels

Related MCP server: Gmail & Google Docs MCP Server

1. Setup Google Cloud Project

  1. Open Google Cloud Console and create a new project (or use an existing one).

  2. Enable the following APIs in APIs & Services > Library:

    • Google Drive API

    • Google Sheets API

    • Google Docs API

    • Google Calendar API

    • Gmail API

  3. Go to APIs & Services > OAuth consent screen:

    • Select External (unless you use Google Workspace organization and want Internal).

    • Fill in the application name, support email, etc.

    • In the Scopes section, add scopes appropriate for this server (see src/google_workspace_mcp/auth.py), or skip it — scopes will be requested automatically during the first consent flow.

    • In the Test users section (if your app is still in "Testing" status), add your Google account email.

  4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID:

    • Application type: Desktop app.

    • Give it any name, for example "Google Workspace MCP".

    • After creation, click Download JSON.

Important note: While your app is in "Testing" status on the consent screen, OAuth tokens will expire every 7 days and you'll need to re-authenticate (delete token.json and run again). For long-term use, publish your app to "In production" status on the OAuth consent screen. (Google approval is not required for personal use with non-sensitive scopes, but Drive/Gmail/Calendar are considered sensitive scopes — Google may ask for verification if you publish for many users; for solo use, Testing status + weekly re-auth is usually sufficient).

2. Installation

cd google_workspace_mcp
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

3. Store Credentials

There are two ways to provide your OAuth client ID/secret to the server — choose one.

Option A — via env in MCP config (no JSON file needed on disk):

Set GOOGLE_WORKSPACE_MCP_CLIENT_ID and GOOGLE_WORKSPACE_MCP_CLIENT_SECRET directly in the env block of your MCP server configuration (see section 5). If both are set, the server will use these and won't look for credentials.json at all.

Option B — credentials.json file on disk:

Save the JSON file you downloaded earlier to:

  • Linux/macOS: ~/.config/google-workspace-mcp/credentials.json

  • Windows: %USERPROFILE%\.config\google-workspace-mcp\credentials.json

Or override the location using the GOOGLE_WORKSPACE_MCP_CREDENTIALS environment variable.

4. First-Time Authentication

When a tool is called for the first time and no token is stored yet, the server will open your browser for Google's consent flow automatically. You can also trigger this manually ahead of time (before using in your MCP client) so the browser opens before you need it:

source venv/bin/activate
python3 -c "from google_workspace_mcp.auth import drive_service; drive_service(); print('OK, token saved.')"

The consent token is saved to ~/.config/google-workspace-mcp/token.json and will refresh automatically as long as it remains valid.

5. Configure Your MCP Client

Register this server with your MCP client following its configuration guidelines.

Claude Desktop

Edit your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry (adjust the path to your project location):

{
  "mcpServers": {
    "google-workspace": {
      "command": "/absolute/path/to/google_workspace_mcp/venv/bin/python",
      "args": ["-m", "google_workspace_mcp.server"]
    }
  }
}

On Windows, use the Windows venv path:

{
  "mcpServers": {
    "google-workspace": {
      "command": "C:\\absolute\\path\\to\\google_workspace_mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "google_workspace_mcp.server"]
    }
  }
}

If using Option A (client ID/secret via env, without credentials.json file), add an env block:

{
  "mcpServers": {
    "google-workspace": {
      "command": "C:\\absolute\\path\\to\\google_workspace_mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "google_workspace_mcp.server"],
      "env": {
        "GOOGLE_WORKSPACE_MCP_CLIENT_ID": "xxxxx.apps.googleusercontent.com",
        "GOOGLE_WORKSPACE_MCP_CLIENT_SECRET": "GOCSPX-xxxxx"
      }
    }
  }
}

After saving the config, restart your MCP client. The tools above will be available to use.

Other MCP Clients

Refer to your client's documentation for how to register custom MCP servers. The server runs on stdio and expects the Python command and arguments shown above.

Project Structure

google_workspace_mcp/
├── pyproject.toml
├── requirements.txt
├── README.md
└── src/google_workspace_mcp/
    ├── server.py       # entry point, registers all tools
    ├── auth.py         # OAuth2 flow + service client cache
    ├── formatting.py   # helper for JSON output & error handling
    └── tools/
        ├── drive.py
        ├── sheets.py
        ├── docs.py
        ├── calendar.py
        └── gmail.py

Security & Limitations

  • Tokens are stored locally in ~/.config/google-workspace-mcp/token.json with 600 permissions (Linux/macOS). Never commit this file or credentials.json to git.

  • drive_trash_file moves files to trash (can be recovered), it does not permanently delete.

  • gmail_send_message and calendar_create_event (with attendees) execute real actions immediately (email sent / invitation sent) without a separate confirmation button at the API level — make sure you've verified the content/recipient before calling these tools.

  • The requested scopes are fairly broad (drive, not drive.file) so you can access files created outside this app. If you want to restrict access only to files created/opened through this app, change the Drive scope in auth.py to drive.file and delete the old token to re-consent.

Adding New Tools

Follow the same pattern in the tools/*.py modules: define a Pydantic input model, then register it via @mcp.tool(name=..., annotations={...}) inside the register(mcp) function. Use handle_google_api_error() from formatting.py for consistent error handling.

License

MIT

Creator

This MCP was created by and is maintained by Heru Arief Wijaya.

Available Tools

27 tools
calendar_create_eventA

Create a new calendar event, optionally inviting attendees.

Attendees receive an email invitation automatically from Google Calendar; there's no separate send step.

Returns: str: JSON with the created event's id, htmlLink, and summary.

Inputs: params (required). Returns: result

calendar_delete_eventA
DestructiveIdempotent

Permanently delete a calendar event (attendees are notified of cancellation).

Returns: str: JSON confirming deletion.

Inputs: params (required). Returns: result

calendar_list_calendarsA
Read-onlyIdempotent

List all calendars the authenticated account can access.

Returns: str: JSON list of {id, summary, primary, access_role}.

Inputs: params (required). Returns: result

calendar_list_eventsA
Read-onlyIdempotent

List upcoming or date-ranged events on a calendar, optionally filtered by text.

Returns: str: JSON list of events with id, summary, description, location, start, end, attendees, organizer, status, and htmlLink.

Inputs: params (required). Returns: result

calendar_update_eventA
DestructiveIdempotent

Update fields on an existing calendar event. Only provided fields change.

Returns: str: JSON with the updated event's id, summary, start, and end.

Inputs: params (required). Returns: result

docs_append_textA

Append plain text to the end of an existing Google Doc.

Returns: str: JSON confirming the document_id and number of characters appended.

Inputs: params (required). Returns: result

docs_create_documentA

Create a new Google Doc, optionally with initial plain-text content.

The new file lands in the account's 'My Drive' root.

Returns: str: JSON with document_id, title, and url.

Inputs: params (required). Returns: result

docs_read_documentA
Read-onlyIdempotent

Read the plain-text content of a Google Doc.

Tables, images, and rich formatting are not preserved — only the text content of paragraphs is extracted, in reading order.

Returns: str: JSON with title, content (plain text, truncated to max_chars), and truncated (bool).

Inputs: params (required). Returns: result

docs_replace_textA
Destructive

Replace all occurrences of a text string throughout a Google Doc.

Returns: str: JSON with the number of replacements made (occurrences_changed).

Inputs: params (required). Returns: result

drive_create_folderA

Create a new folder in Google Drive.

Returns: str: JSON with the created folder's id, name, and webViewLink.

Inputs: params (required). Returns: result

drive_download_fileA
Read-onlyIdempotent

Download a Drive file to a local path, exporting Google-native files if needed.

Returns: str: JSON with the saved local path and byte size, or an error message (e.g. if export_mime_type is required but missing).

Inputs: params (required). Returns: result

drive_get_file_metadataA
Read-onlyIdempotent

Get full metadata for a single Drive file or folder.

Returns: str: JSON object with id, name, mimeType, size, modifiedTime, createdTime, webViewLink, parents, owners, and permissions summary.

Inputs: params (required). Returns: result

drive_read_file_contentA
Read-onlyIdempotent

Read the text content of a Drive file directly into the conversation.

Google Docs export as plain text, Google Sheets as CSV, Google Slides as plain text. Other text-based files (txt, md, csv, json, code files) are read directly. Binary files (images, PDFs, etc.) are not supported here — use drive_download_file to save them locally instead.

Returns: str: The file's text content (truncated to max_chars), or an error message explaining why the file couldn't be read as text.

Inputs: params (required). Returns: result

drive_search_filesA
Read-onlyIdempotent

Search for files and folders in Google Drive.

Accepts either plain text (matched against file names) or a raw Drive query string for advanced filtering by MIME type, folder, date, etc.

Returns: str: JSON with keys files (list of {id, name, mimeType, size, modifiedTime, webViewLink, parents, owners}) and next_page_token (str or null) for pagination via a follow-up call.

Inputs: params (required). Returns: result

drive_trash_fileA
DestructiveIdempotent

Move a Drive file to the trash (recoverable, not permanent deletion).

Returns: str: JSON confirming the file id and its new trashed status.

Inputs: params (required). Returns: result

drive_upload_fileB

Upload a local file to Google Drive.

Returns: str: JSON with the created file's id, name, mimeType, and webViewLink.

Inputs: params (required). Returns: result

gmail_create_draftA

Create a draft email without sending it.

Returns: str: JSON with the draft's id and message id.

Inputs: params (required). Returns: result

gmail_get_messageA
Read-onlyIdempotent

Get the full content of a single Gmail message, including plain-text body.

Returns: str: JSON with from, to, subject, date, body (plain text), and labels.

Inputs: params (required). Returns: result

gmail_list_labelsA
Read-onlyIdempotent

List all Gmail labels (system labels like INBOX plus user-created ones).

Returns: str: JSON list of {id, name, type}.

Inputs: params (required). Returns: result

gmail_search_messagesA
Read-onlyIdempotent

Search or list Gmail messages using Gmail's search syntax.

Returns lightweight results (id, threadId, snippet, from, subject, date) — use gmail_get_message for the full body of a specific message.

Returns: str: JSON list of message summaries.

Inputs: params (required). Returns: result

gmail_send_messageA

Send an email immediately from the authenticated Gmail account.

This sends right away with no draft/confirmation step on the API side — confirm intent with the user before calling this tool.

Returns: str: JSON with the sent message's id and threadId.

Inputs: params (required). Returns: result

sheets_append_valuesA

Append rows after the last row of existing data in a table/range.

Unlike sheets_write_range, this never overwrites existing rows — the Sheets API finds the end of the data and inserts after it.

Returns: str: JSON with updated_range describing where the new rows landed.

Inputs: params (required). Returns: result

sheets_clear_rangeA
DestructiveIdempotent

Clear all values in a range, leaving cell formatting intact.

Returns: str: JSON confirming the cleared range.

Inputs: params (required). Returns: result

sheets_create_spreadsheetA

Create a new Google Sheets spreadsheet, optionally with named tabs.

The new file lands in the account's 'My Drive' root; use drive_upload_file's sibling tools (e.g. a follow-up move) if it needs to live in a specific folder.

Returns: str: JSON with spreadsheet_id, title, and url.

Inputs: params (required). Returns: result

sheets_list_tabsA
Read-onlyIdempotent

List all sheet tabs in a spreadsheet with their IDs and dimensions.

Returns: str: JSON list of {sheet_id, title, index, row_count, column_count}.

Inputs: params (required). Returns: result

sheets_read_rangeA
Read-onlyIdempotent

Read cell values from a range in a Google Sheet.

Returns: str: JSON with range (the resolved range) and values (2D array of row data as returned by the Sheets API; empty trailing cells are omitted by Google's API).

Inputs: params (required). Returns: result

sheets_write_rangeA
DestructiveIdempotent

Write values into a range, overwriting whatever is currently there.

The number of rows/columns in values determines how much of the sheet is overwritten starting at the top-left of range. Use sheets_append_values instead if you want to add new rows without overwriting existing data.

Returns: str: JSON with updated_range, updated_rows, and updated_cells.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 27 tools

    Disambiguation4/5

    Service prefixes and distinct action verbs make most tools easy to tell apart. The only real overlap is that drive_read_file_content can also read Google Docs/Sheets, which partially duplicates docs_read_document and sheets_read_range, but the descriptions clarify the intended use.

    Naming Consistency5/5

    Every tool follows a consistent snake_case service_prefix + verb_noun pattern, such as drive_upload_file, sheets_append_values, calendar_create_event, and gmail_send_message. There is no mixing of conventions or vague naming.

    Tool Count4/5

    27 tools is above the typical sweet spot, but the server covers five distinct Google Workspace apps, and no single app has more than 7 tools. The count feels slightly heavy but is reasonable given the broad integration scope.

    Completeness4/5

    Core lifecycle workflows are covered across Drive, Sheets, Docs, Calendar, and Gmail: search/read/create/update/delete are largely present. Notable gaps exist such as Drive move/update, Sheet row deletion, and Gmail trash/label management, but agents can complete primary tasks without dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers