google-workspace-mcp
Offers capabilities to search, read, send, draft, and manage labels in Gmail.
Provides tools to list calendars, and to list, create, update, and delete events in Google Calendar.
Enables creating, reading, appending text to, and replacing text in Google Docs documents.
Provides tools to search, retrieve, upload, create, download, and trash files in Google Drive.
Allows reading, writing, appending, clearing, and creating spreadsheets, as well as listing tabs in Google Sheets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-workspace-mcp Find the latest budget spreadsheet in Drive and show me its contents."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
google-workspace-mcp
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 |
|
Sheets |
|
Docs |
|
Calendar |
|
Gmail |
|
Related MCP server: Gmail & Google Docs MCP Server
1. Setup Google Cloud Project
Open Google Cloud Console and create a new project (or use an existing one).
Enable the following APIs in APIs & Services > Library:
Google Drive API
Google Sheets API
Google Docs API
Google Calendar API
Gmail API
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.
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.jsonand 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.jsonWindows:
%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.jsonWindows:
%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.pySecurity & Limitations
Tokens are stored locally in
~/.config/google-workspace-mcp/token.jsonwith600permissions (Linux/macOS). Never commit this file orcredentials.jsonto git.drive_trash_filemoves files to trash (can be recovered), it does not permanently delete.gmail_send_messageandcalendar_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, notdrive.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 inauth.pytodrive.fileand 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
Creator
This MCP was created by and is maintained by Heru Arief Wijaya.
Available Tools
27 toolscalendar_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_eventADestructiveIdempotent
Permanently delete a calendar event (attendees are notified of cancellation).
Returns: str: JSON confirming deletion.
Inputs: params (required). Returns: result
calendar_list_calendarsARead-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_eventsARead-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_eventADestructiveIdempotent
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_documentARead-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_textADestructive
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_fileARead-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_metadataARead-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_contentARead-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_filesARead-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_fileADestructiveIdempotent
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_messageARead-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_labelsARead-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_messagesARead-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_rangeADestructiveIdempotent
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_tabsARead-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_rangeARead-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_rangeADestructiveIdempotent
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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables MCP-compatible AI assistants to interact with a user's Google Drive, including listing, searching, reading, creating, updating, and deleting files, with authentication via Google OAuth.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to send Gmail emails, create drafts, and append content to Google Docs through MCP tools. Provides secure OAuth-based integration with Google Workspace.ISC
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to access and manage Google Workspace services such as Gmail, Drive, Docs, Sheets, Calendar, and Slides through the MCP protocol, with built-in OAuth 2.0 authentication and read/write tool support.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible AI agents to create and send Gmail messages and append text to existing Google Docs through OAuth-authenticated tools.MIT