Google Workspace MCP connector
Provides tools for searching and reading Gmail messages and threads, sending emails and replies, creating and sending drafts, downloading attachments, and managing labels and message state such as read/unread, star, archive, and trash.
Provides Google Ads tools for listing accounts, retrieving campaign, ad group, keyword, ad, and search-term performance with cost, conversions, and ROAS, running read-only GAQL queries, pausing or enabling entities, and updating campaign budgets.
Provides read-only Google Analytics 4 tools for listing properties, retrieving overview metrics, running custom reports with dimensions and metrics, accessing realtime data, and getting metadata.
Provides tools for creating Google Docs from Markdown, reading document content, inserting and replacing text, deleting ranges, inserting tables and images, and performing batch document updates.
Provides tools for searching and listing Drive files and folders, reading, uploading, downloading, and exporting files, creating folders, moving, copying, renaming, and trashing files, and managing sharing permissions.
Provides tools for creating and reading spreadsheets, writing formulas and values, appending rows, clearing ranges, managing tabs, formatting cells, adding charts, analyzing data, and performing batch updates.
Provides tools for creating presentations, reading slides, adding slides, replacing and setting text, adding speaker notes, images, and text boxes, managing slide order and duplication, retrieving thumbnails, and performing batch updates.
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 connector search my Gmail for unread emails from my boss this week"
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 connector
An MCP server and Claude plugin that connects Claude to Gmail, Google Drive, Docs, Sheets, Slides, Google Analytics 4 and Google Ads. It runs locally and signs in with your own Google account. Your tokens stay on your machine.
Requires Node.js 20+.
Install
Claude Code (plugin)
This repo is a plugin marketplace. The plugin in plugin/ contains the bundled server (no npm install needed) and two skills.
claude plugin marketplace add animesh-ex/google-workspace-mcpclaude plugin install google-workspace@google-workspace-local --scope userThen start a new session and run /google-workspace:setup (or say "connect Google"). Claude imports the client_secret_*.json you downloaded (see Setup below) and opens Google sign-in in your browser.
Claude app (Cowork)
Download google-workspace.plugin from the latest release and open it in the Claude app to install.
Other MCP clients
Run node plugin/server/index.mjs as a stdio MCP server (see "Add it to Claude" below).
After changing code in src/, run npm run build:plugin to refresh plugin/server/.
Related MCP server: Google Workspace MCP
What it can do (72 tools)
Service | Tools |
Gmail |
|
Attachments |
|
Drive |
|
Sharing |
|
Docs |
|
Sheets |
|
Slides |
|
Google Analytics 4 |
|
Google Ads |
|
Every tool takes either a file ID or a full Google URL. Create tools take an optional folderId so new files land in the right Drive folder.
Setup (one time, about 10 minutes)
1. Create a Google Cloud OAuth client
Go to https://console.cloud.google.com/ and create (or pick) a project.
APIs & Services → Library: enable Gmail API, Google Drive API, Google Docs API, Google Sheets API, Google Slides API, Google Analytics Data API, Google Analytics Admin API and Google Ads API.
APIs & Services → OAuth consent screen (or "Google Auth Platform"): choose External, fill in the app name and your email, and under Test users add the Google account(s) you'll sign in with.
Credentials → Create credentials → OAuth client ID. Pick the application type Desktop app. Download the JSON.
Save the file as:
C:\Users\<you>\.google-workspace-mcp\credentials.jsonYou can choose a different folder by setting
GOOGLE_WORKSPACE_MCP_DIR, point at a file withGOOGLE_OAUTH_CREDENTIALS, or setGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETinstead.
While the app is in "Testing" mode, Google expires refresh tokens after 7 days. When that happens, run
npm run authagain. To avoid it, publish the app ("In production"); for personal use you can skip Google's verification and accept the "unverified app" warning.
2. Build and sign in
cd ~/projects/google-workspace-mcp
npm install
npm run build
npm run authnpm run auth opens your browser and asks for consent. When you approve, it saves token.json next to credentials.json.
2b. Google Ads developer token (only for ads_* tools)
The Google Ads API needs a developer token in addition to sign-in:
Sign in to a Google Ads manager (MCC) account that has access to your ad accounts (create one free at https://ads.google.com/home/tools/manager-accounts/ if needed).
Tools → Setup → API Center, fill in the form and copy the developer token. New tokens start at "Test" access (test accounts only); apply for Basic access in the same page to use real accounts.
Ask Claude to run
google_setupwithconfigure_adsand your token (plus the manager account ID), or createC:\Users\<you>\.google-workspace-mcp\ads.jsonyourself:{ "developerToken": "YOUR_TOKEN", "loginCustomerId": "1234567890" }Environment variables
GOOGLE_ADS_DEVELOPER_TOKEN/GOOGLE_ADS_LOGIN_CUSTOMER_IDalso work.GOOGLE_ADS_API_VERSIONoverrides the API version (defaultv26).
The Google account you sign in with must have access to the Analytics properties and Ads accounts you want to use.
3. Add it to Claude
Claude Code (all projects):
claude mcp add --scope user google-workspace -- node /path/to/google-workspace-mcp/plugin/server/index.mjsClaude Desktop (%APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"google-workspace": {
"command": "node",
"args": ["/path/to/google-workspace-mcp/plugin/server/index.mjs"]
}
}
}Restart Claude, then try prompts like:
"Find unread emails from my accountant this week and summarize them."
"Reply to that thread saying I'll send it Friday, and attach the Q3 report from Drive."
"Create a sheet from this CSV, analyze revenue by region, and add a column chart."
"Build a 6-slide deck on our launch plan with speaker notes in my 'Marketing' folder, then share it with alex@example.com as a commenter."
Scopes requested
gmail.modify (read, send, label; it can't permanently delete mail), drive, documents, spreadsheets, presentations, analytics.readonly (GA4 is read-only), adwords (Google Ads reporting and changes).
If you signed in before Analytics/Ads were added, google_setup → status lists missingScopes; run sign_in again to grant them.
Safety notes
Destructive tools (
drive_trash,drive_update_permission,sheets_clear,docs_delete_range,slides_manage_slide, andsheets_manage_tab) are markeddestructiveHintso clients can ask before running them. Drive deletes go to the trash, never permanent deletion.Claude Code asks before each tool call unless you allow it. Consider leaving
gmail_send,gmail_reply,drive_share,ads_set_statusandads_set_campaign_budgeton "ask".Google Ads changes take effect immediately and affect spend. Both Ads change tools support
validateOnly: truefor a dry run.token.jsongives access to your account. Keep it private.
Development
npm run build # compile to dist/
npm run typecheck # type-check onlySource: src/auth.ts (OAuth), src/util.ts (shared helpers), src/tools/{gmail,drive,docs,sheets,slides}.ts.
Available Tools
72 toolsads_ad_group_performanceCRead-only
Ad group performance for a date range, optionally within one campaign.
Inputs: customerId (required), limit, endDate, dateRange, +3 more.
ads_ad_performanceCRead-only
Ad-level performance including responsive search ad headlines/descriptions.
Inputs: customerId (required), limit, endDate, dateRange, +3 more.
ads_campaign_performanceBRead-only
Campaign performance for a date range: status, type, daily budget, impressions, clicks, CTR, avg CPC, cost, conversions, conversion value, cost/conversion and ROAS.
Inputs: customerId (required), limit, endDate, dateRange, +3 more.
ads_keyword_performanceBRead-only
Search keyword performance with match type and quality score.
Inputs: customerId (required), limit, endDate, dateRange, +3 more.
ads_list_accountsARead-only
List Google Ads accounts this Google login can access (IDs, names, currency, whether each is a manager), including client accounts under managers.
Inputs: no named parameters.
ads_queryARead-only
Run any read-only GAQL query against a Google Ads account (e.g. SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS). Money fields ending in _micros are returned in currency units.
Inputs: query (required), customerId (required), limit, loginCustomerId.
ads_search_termsBRead-only
Search terms report: the actual queries that triggered ads, with cost and conversions (find wasted spend and new keywords).
Inputs: customerId (required), limit, endDate, minCost, +4 more.
ads_set_campaign_budgetADestructive
Change a campaign's daily budget (in account currency). Shared budgets affect every campaign using them. Use validateOnly=true to dry-run. Always confirm the amount with the user first.
Inputs: campaignId (required), customerId (required), dailyBudget (required), validateOnly, +1 more.
ads_set_statusADestructive
Pause or enable campaigns, ad groups, ads or keywords. ENABLED resumes spending. Use validateOnly=true to dry-run. Always confirm with the user first.
Inputs: ids (required), entity (required), status (required), customerId (required), +2 more.
docs_batch_updateB
Advanced: send raw Google Docs API batchUpdate requests (for styling, page breaks, headers, etc.).
Inputs: requests (required), documentId (required).
docs_createB
Create a Google Doc, optionally with Markdown content (headings, bold/italic, links, bullet & numbered lists, code) and in a given Drive folder.
Inputs: title (required), folderId, markdown.
docs_delete_rangeBDestructive
Delete content between two indices (get indices from docs_read structured).
Inputs: endIndex (required), documentId (required), startIndex (required).
docs_insert_imageC
Insert an image from a public URL into a Doc.
Inputs: imageUrl (required), documentId (required), index, widthPt.
docs_insert_markdownB
Append Markdown content to the end of a Doc, or insert it at a specific index (from docs_read structured).
Inputs: markdown (required), documentId (required), index.
docs_insert_tableB
Insert a table filled with data (first row = header, bolded) at the end of a Doc or at an index.
Inputs: rows (required), documentId (required), index.
docs_readARead-only
Read a Google Doc. format 'markdown' returns readable text; 'structured' returns each paragraph/table with its start/end index (needed for precise edits).
Inputs: documentId (required), format.
docs_replace_textB
Find and replace text throughout a Doc (e.g. fill {{placeholders}} in a template).
Inputs: documentId (required), replacements (required).
drive_aboutARead-only
Show the signed-in Google account and Drive storage usage.
Inputs: no named parameters.
drive_copyB
Make a copy of a file (e.g. duplicate a template doc/sheet/deck).
Inputs: fileId (required), name, folderId.
drive_create_folderC
Create a folder in Drive.
Inputs: name (required), parentId.
drive_download_fileA
Download a Drive file to a local folder. Google Docs/Sheets/Slides are exported (format: pdf, docx, xlsx, csv, pptx, txt, md, html).
Inputs: fileId (required), saveDir (required), format.
drive_get_fileBRead-only
Get metadata for a Drive file (ID or URL).
Inputs: fileId (required).
drive_list_folderBRead-only
List the contents of a Drive folder ('root' = My Drive).
Inputs: folderId, pageSize, pageToken.
drive_list_permissionsCRead-only
List who a file is shared with.
Inputs: fileId (required).
drive_moveC
Move a file or folder into another folder.
Inputs: fileId (required), newParentId (required).
drive_read_file_textARead-only
Read a file's content as text: Google Docs (markdown), Sheets (CSV of first tab), Slides (text), or plain text/CSV/JSON files.
Inputs: fileId (required), maxChars.
drive_searchBRead-only
Search Google Drive files by name/full text, type, or folder. Optionally pass a raw Drive 'q' query.
Inputs: name, type, orderBy, folderId, +5 more.
drive_trashADestructive
Move a file/folder to the Drive trash (recoverable for 30 days), or restore it.
Inputs: fileId (required), restore.
drive_update_metadataB
Rename a file, change its description, or star/unstar it.
Inputs: fileId (required), name, starred, description.
drive_update_permissionBDestructive
Change a collaborator's role, or remove their access (role 'remove').
Inputs: role (required), fileId (required), permissionId (required).
drive_upload_fileA
Upload a local file to Drive. Set convert=true to turn .docx/.xlsx/.csv/.pptx/.txt into native Google Docs/Sheets/Slides.
Inputs: localPath (required), name, convert, folderId.
ga_get_metadataARead-only
List the dimensions and metrics available for a GA4 property (including custom ones). Optional search text filters the list.
Inputs: propertyId (required), search.
ga_list_propertiesARead-only
List the Google Analytics 4 accounts and properties this Google account can access (with property IDs).
Inputs: no named parameters.
ga_overviewBRead-only
Quick GA4 performance summary: users, new users, sessions, engagement rate, avg session duration, views, key events (conversions) and revenue, broken down by a chosen dimension.
Inputs: propertyId (required), limit, endDate, breakdown, +1 more.
ga_realtimeBRead-only
GA4 realtime report (last 30 minutes): active users by a dimension such as country, unifiedScreenName, deviceCategory.
Inputs: propertyId (required), limit, metrics, dimensions.
ga_run_reportBRead-only
Run a custom GA4 report with any dimensions/metrics (see ga_get_metadata for names). Supports filters, ordering, comparison of two date ranges.
Inputs: metrics (required), propertyId (required), desc, limit, +9 more.
gmail_create_draftB
Create an email draft (not sent). Supports attachments.
Inputs: body (required), subject (required), cc, to, +4 more.
gmail_create_labelC
Create a new Gmail label.
Inputs: name (required).
gmail_download_attachmentA
Download an email attachment to a local path, or save it straight into Google Drive.
Inputs: filename (required), messageId (required), attachmentId (required), saveDir, +1 more.
gmail_list_draftsCRead-only
List email drafts.
Inputs: maxResults.
gmail_list_labelsARead-only
List Gmail labels (system and user).
Inputs: no named parameters.
gmail_modifyB
Organize messages: mark read/unread, star, archive, move to trash, or add/remove labels. Label names or IDs accepted.
Inputs: action (required), messageIds (required), addLabels, removeLabels.
gmail_read_messageBRead-only
Read a full email: headers, plain-text body, and attachment list (with attachmentIds).
Inputs: messageId (required).
gmail_read_threadBRead-only
Read every message in an email thread/conversation in order.
Inputs: threadId (required).
gmail_replyA
Reply (or reply-all) to an existing email, keeping it in the same thread. Supports attachments.
Inputs: body (required), messageId (required), cc, html, +4 more.
gmail_searchARead-only
Search Gmail using Gmail query syntax (e.g. 'from:alice is:unread newer_than:7d', 'has:attachment subject:invoice'). Returns message headers and snippets.
Inputs: query, pageToken, maxResults.
gmail_sendB
Send a new email. Supports cc/bcc, HTML bodies, and attachments from local files or Google Drive.
Inputs: to (required), body (required), subject (required), cc, +4 more.
gmail_send_draftC
Send an existing draft.
Inputs: draftId (required).
google_setupA
Set up or check the Google connection. Actions: 'status' (what's configured), 'import_credentials' (copy a downloaded Desktop-app OAuth client JSON into place; omit path to use the newest client_secret_*.json in Downloads), 'sign_in' (opens the browser for Google consent and waits up to 5 minutes), 'sign_out' (deletes the saved token), 'configure_ads' (save a Google Ads developer token and optional manager account ID).
Inputs: action (required), developerToken, credentialsPath, loginCustomerId.
sheets_add_chartC
Add a chart (column, bar, line, area, pie, scatter) built from a data range on a tab.
Inputs: tab (required), endRow (required), startRow (required), domainCol (required), +4 more.
sheets_analyzeARead-only
Analyze a table in a range (first row = headers): per-column type, count, blanks, distinct values, and for numeric columns sum/mean/median/min/max/stdev; top values for text columns. Optional group-by summary.
Inputs: range (required), spreadsheetId (required), groupBy, aggregateColumns.
sheets_append_rowsB
Append rows after the last row of data in a tab.
Inputs: rows (required), spreadsheetId (required), tab.
sheets_batch_updateB
Advanced: send raw Sheets API batchUpdate requests (conditional formatting, filters, pivot tables, etc.).
Inputs: requests (required), spreadsheetId (required).
sheets_clearBDestructive
Clear the values in a range (formatting is kept).
Inputs: range (required), spreadsheetId (required).
sheets_createC
Create a Google Sheet with optional tab names and initial data for the first tab.
Inputs: title (required), data, tabs, folderId.
sheets_formatC
Format a range on one tab: bold, colors, number format (e.g. '$#,##0.00', '0.0%', 'yyyy-mm-dd'), alignment, borders.
Inputs: tab (required), endCol (required), endRow (required), startCol (required), +11 more.
sheets_get_infoARead-only
List a spreadsheet's tabs with their sizes, plus title and URL.
Inputs: spreadsheetId (required).
sheets_manage_tabCDestructive
Add, rename, duplicate or delete a tab.
Inputs: tab (required), action (required), spreadsheetId (required), newName.
sheets_readCRead-only
Read values from a range in A1 notation, e.g. 'Sheet1!A1:D50' or just 'Sheet1' for the whole tab.
Inputs: range (required), spreadsheetId (required), valueRender.
sheets_writeB
Write values to a range (starting cell like 'Sheet1!B2' is enough). Formulas like '=SUM(A1:A9)' are evaluated.
Inputs: range (required), values (required), spreadsheetId (required), raw.
slides_add_imageB
Place an image (public URL) on a slide. Position/size in points (deck is usually 720×405 pt).
Inputs: slide (required), imageUrl (required), presentationId (required), x, +3 more.
slides_add_slidesB
Add one or more slides to an existing presentation (at the end or at a 0-based position).
Inputs: slides (required), presentationId (required), insertionIndex.
slides_add_text_boxC
Add a text box to a slide. Position/size in points.
Inputs: text (required), slide (required), presentationId (required), x, +5 more.
slides_batch_updateB
Advanced: send raw Google Slides API batchUpdate requests (shapes, tables, styling, etc.).
Inputs: requests (required), presentationId (required).
slides_createB
Create a Google Slides presentation, optionally with slides (layout, title, bullets, two columns, speaker notes, images).
Inputs: title (required), slides, folderId.
slides_get_thumbnailARead-only
Get a PNG thumbnail URL of a slide (to visually check it).
Inputs: slide (required), presentationId (required), size.
slides_manage_slideCDestructive
Delete, duplicate, or move a slide.
Inputs: slide (required), action (required), presentationId (required), toIndex.
slides_readARead-only
Read a presentation: every slide's text (by placeholder), tables, image count, and speaker notes.
Inputs: presentationId (required).
slides_replace_textB
Find and replace text across all slides (or only some), e.g. fill {{placeholders}} in a template deck.
Inputs: replacements (required), presentationId (required), onlySlideIds.
slides_set_notesC
Set the speaker notes of a slide.
Inputs: notes (required), slide (required), presentationId (required).
slides_set_textA
Replace all text inside one shape/text box (objectId from slides_read).
Inputs: text (required), objectId (required), presentationId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 72 tools
Product-prefixed namespaces (gmail_, drive_, docs_, sheets_, slides_, ga_, ads_) plus action-specific suffixes make almost every tool clearly distinguishable, e.g. gmail_send vs gmail_send_draft vs gmail_reply. The only soft overlaps are the generic drive_read_file_text versus the per-product readers (sheets_read, docs_read, slides_read), and the three *_batch_update raw-API escape hatches which sit near their specific counterparts, but the descriptions explicitly frame these as advanced/generic alternatives.
The set follows a very predictable <product>_<verb>_<object> snake_case convention (drive_get_file, sheets_append_rows, slides_set_notes, ads_set_status). A few tools deviate by using noun-only or adjectival forms (ga_overview, drive_about, google_setup, ads_query), which breaks the pattern slightly without hurting readability.
72 tools is far beyond what an agent can hold in working context, and the surface is heavy even though it is justified by bundling seven distinct Google products. Each individual domain is reasonably scoped (5-17 tools), but the aggregate volume forces selection errors and bloats every prompt.
Per-product lifecycle coverage is strong: Gmail spans search/read/thread/send/reply/drafts/attachments/labels/modify, Drive covers the full file and sharing lifecycle, and Docs/Sheets/Slides each offer create, read, edit, formatting, and raw batchUpdate escape hatches. Gaps remain at the edges — no Google Calendar/Contacts/Tasks surface despite 'Workspace' branding, no label deletion, and Ads is read-plus-status/budget only with no campaign creation.
Maintenance
Related MCP Connectors
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables Claude AI to directly interact with Gmail through natural language for comprehensive email management including sending, reading, searching, organizing, and managing drafts and labels. Uses secure OAuth authentication and runs locally without third-party servers.MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Google Workspace services (Gmail, Calendar, Drive, Docs, Sheets, Chat, Slides, People) through natural language using Claude Desktop, Claude Code CLI, and other MCP clients.491 npm3MIT
- FlicenseNot gradedqualityBmaintenanceExposes 25 tools for Claude Code across Gmail, Calendar, Drive, Docs, Sheets, and Slides. Supports multi-account, local-first, encrypted OAuth tokens.102-
- AlicenseNot gradedqualityDmaintenanceGives Claude read/write access to your own Gmail, Google Docs, Google Sheets, and Google Tasks via a tiny always-on web service.ISC