Skip to main content
Glama
Google Workspace MCP connector

Google Workspace MCP connector

by animesh-ex

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-mcp
claude plugin install google-workspace@google-workspace-local --scope user

Then 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

gmail_search, gmail_read_message, gmail_read_thread, gmail_send, gmail_reply (reply / reply-all, same thread, or save as draft), gmail_create_draft, gmail_list_drafts, gmail_send_draft, gmail_download_attachment (save to disk or straight into Drive), gmail_modify (read/unread, star, archive, trash, labels), gmail_list_labels, gmail_create_label

Attachments

gmail_send, gmail_reply and gmail_create_draft take attachmentPaths (local files) and driveFileIds. Docs and Slides are attached as PDF, Sheets as XLSX.

Drive

drive_search, drive_list_folder, drive_get_file, drive_read_file_text, drive_create_folder, drive_upload_file (can convert to Google formats), drive_download_file (export to pdf/docx/xlsx/csv/pptx/md), drive_move, drive_copy, drive_update_metadata (rename/star/description), drive_trash (recoverable), drive_about

Sharing

drive_share (user, group, domain or anyone with the link; reader/commenter/writer/owner; optional notification message), drive_list_permissions, drive_update_permission (change role or remove access)

Docs

docs_create (from Markdown), docs_read (Markdown or indexed structure), docs_insert_markdown, docs_replace_text, docs_delete_range, docs_insert_table, docs_insert_image, docs_batch_update

Sheets

sheets_create, sheets_get_info, sheets_read, sheets_write (formulas work), sheets_append_rows, sheets_clear, sheets_manage_tab, sheets_format, sheets_add_chart, sheets_analyze (per-column stats and group-by summaries), sheets_batch_update

Slides

slides_create (whole deck with layouts, bullets, two columns, speaker notes and images), slides_read, slides_add_slides, slides_replace_text, slides_set_text, slides_set_notes, slides_add_image, slides_add_text_box, slides_manage_slide (delete/duplicate/move), slides_get_thumbnail, slides_batch_update

Google Analytics 4

ga_list_properties, ga_overview (users, sessions, engagement, key events, revenue by channel/source/campaign/page/country/device/date…), ga_run_report (any dimensions/metrics, filters, period comparison), ga_realtime, ga_get_metadata

Google Ads

ads_list_accounts, ads_campaign_performance, ads_ad_group_performance, ads_keyword_performance, ads_search_terms, ads_ad_performance (all with cost/conversion and ROAS), ads_query (any read-only GAQL), ads_set_status (pause/enable campaigns, ad groups, ads, keywords), ads_set_campaign_budget

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

  1. Go to https://console.cloud.google.com/ and create (or pick) a project.

  2. 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.

  3. 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.

  4. Credentials → Create credentials → OAuth client ID. Pick the application type Desktop app. Download the JSON.

  5. Save the file as:

    C:\Users\<you>\.google-workspace-mcp\credentials.json

    You can choose a different folder by setting GOOGLE_WORKSPACE_MCP_DIR, point at a file with GOOGLE_OAUTH_CREDENTIALS, or set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET instead.

While the app is in "Testing" mode, Google expires refresh tokens after 7 days. When that happens, run npm run auth again. 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 auth

npm 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:

  1. 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).

  2. 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.

  3. Ask Claude to run google_setup with configure_ads and your token (plus the manager account ID), or create C:\Users\<you>\.google-workspace-mcp\ads.json yourself:

    { "developerToken": "YOUR_TOKEN", "loginCustomerId": "1234567890" }

    Environment variables GOOGLE_ADS_DEVELOPER_TOKEN / GOOGLE_ADS_LOGIN_CUSTOMER_ID also work. GOOGLE_ADS_API_VERSION overrides the API version (default v26).

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.mjs

Claude 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, and sheets_manage_tab) are marked destructiveHint so 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_status and ads_set_campaign_budget on "ask".

  • Google Ads changes take effect immediately and affect spend. Both Ads change tools support validateOnly: true for a dry run.

  • token.json gives access to your account. Keep it private.

Development

npm run build      # compile to dist/
npm run typecheck  # type-check only

Source: src/auth.ts (OAuth), src/util.ts (shared helpers), src/tools/{gmail,drive,docs,sheets,slides}.ts.

Available Tools

72 tools
ads_ad_group_performanceC
Read-only

Ad group performance for a date range, optionally within one campaign.

Inputs: customerId (required), limit, endDate, dateRange, +3 more.

ads_ad_performanceC
Read-only

Ad-level performance including responsive search ad headlines/descriptions.

Inputs: customerId (required), limit, endDate, dateRange, +3 more.

ads_campaign_performanceB
Read-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_performanceB
Read-only

Search keyword performance with match type and quality score.

Inputs: customerId (required), limit, endDate, dateRange, +3 more.

ads_list_accountsA
Read-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_queryA
Read-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_termsB
Read-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_budgetA
Destructive

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_statusA
Destructive

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_rangeB
Destructive

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_readA
Read-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_aboutA
Read-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_fileB
Read-only

Get metadata for a Drive file (ID or URL).

Inputs: fileId (required).

drive_list_folderB
Read-only

List the contents of a Drive folder ('root' = My Drive).

Inputs: folderId, pageSize, pageToken.

drive_list_permissionsC
Read-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_textA
Read-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_shareB

Share a file/folder (Doc, Sheet, Slides, anything) with a person, group, domain, or anyone with the link.

Inputs: fileId (required), role, type, domain, +3 more.

drive_trashA
Destructive

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_permissionB
Destructive

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_metadataA
Read-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_propertiesA
Read-only

List the Google Analytics 4 accounts and properties this Google account can access (with property IDs).

Inputs: no named parameters.

ga_overviewB
Read-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_realtimeB
Read-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_reportB
Read-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_draftsC
Read-only

List email drafts.

Inputs: maxResults.

gmail_list_labelsA
Read-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_messageB
Read-only

Read a full email: headers, plain-text body, and attachment list (with attachmentIds).

Inputs: messageId (required).

gmail_read_threadB
Read-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_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_analyzeA
Read-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_clearB
Destructive

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_infoA
Read-only

List a spreadsheet's tabs with their sizes, plus title and URL.

Inputs: spreadsheetId (required).

sheets_manage_tabC
Destructive

Add, rename, duplicate or delete a tab.

Inputs: tab (required), action (required), spreadsheetId (required), newName.

sheets_readC
Read-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_thumbnailA
Read-only

Get a PNG thumbnail URL of a slide (to visually check it).

Inputs: slide (required), presentationId (required), size.

slides_manage_slideC
Destructive

Delete, duplicate, or move a slide.

Inputs: slide (required), action (required), presentationId (required), toIndex.

slides_readA
Read-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

    B3.1/5.0

    Scored across 72 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers