Skip to main content
Glama

GoogleMCP

GoogleMCP is a local MCP server that gives an MCP client (Claude Desktop, Claude Code, Cursor, Hermes Agent, or any other stdio client) scoped access to your own Google account. It runs on your machine over stdio: it opens no network listener, has no HTTP mode, and is not meant to be hosted. Google API calls use a refresh token from your own Desktop OAuth client, kept in the OS keyring by default.

  • Read-only by default. Write tools need a per-product opt-in, and destructive tools (delete, trash, send) need a second opt-in.

  • Covers Workspace apps and other Google APIs: Tasks, YouTube, Search Console, Google Analytics, Photos, Apps Script, and more (table below).

  • Terraform enables the Google APIs. The OAuth consent screen and the Desktop OAuth client have no API, so you create them in the console.

Each person who uses GoogleMCP creates their own Google Cloud project and OAuth client. There is no shared client and no central service.

Documentation index: docs/README.md.

Products

catalog/services.json is the source of truth; Terraform and the server both read it, and tests/test_readme.py checks this table against it. Scopes and tools per product are in docs/inventory.md.

Key

Product

Default

Why off by default

tasks

Google Tasks

on

gmail

Gmail

on

calendar

Google Calendar

on

drive

Google Drive

on

docs

Google Docs

on

sheets

Google Sheets

on

slides

Google Slides

on

forms

Google Forms

on

people

People and Contacts

on

meet

Google Meet

off

Meet REST API needs a Google Workspace account

driveactivity

Drive Activity

on

chat

Google Chat

off

Needs a Business or Enterprise Workspace account and a Chat app configured in the console

youtube

YouTube Data

on

youtube_analytics

YouTube Analytics

on

youtube_reporting

YouTube Reporting

off

Reporting jobs are created and kept on Google's side

analytics

Google Analytics

on

searchconsole

Search Console

on

appsscript

Apps Script

off

Can run code in your account; also needs a manual per-user setting

photos

Google Photos (Library app-created data and Picker)

on

"Default on" means the product is enabled when GOOGLEMCP_PRODUCTS is unset, still read-only. Gmail and Drive use restricted scopes, and YouTube Data has a daily quota. Google removed the broad Photos Library scopes on 2025-03-31, so the Library API reaches only media this app created; the Picker API reads photos you select (Photos API updates). Google Tasks setup on its own: docs/tasks.md.

Related MCP server: gmail-mcp

Quick start

You need Python 3.12+, uv, the gcloud CLI, and a Google account. Terraform 1.9+ is optional (it is one of two ways to enable APIs).

1. Install

git clone https://github.com/1solomonwakhungu/googlemcp
cd googlemcp
uv sync
uv run googlemcp products      # what is enabled; no Google call

Or run it without a checkout (not published on PyPI):

uvx --from git+https://github.com/1solomonwakhungu/googlemcp googlemcp products

The Terraform module and scripts/acceptance/verify_stored_client.py live in the repository, so clone it if you want either.

2. Create a Google Cloud project and enable the APIs

gcloud auth login
gcloud projects create PROJECT_ID --name="GoogleMCP"
gcloud config set project PROJECT_ID

Then enable the APIs for the products you want, either with Terraform (docs/terraform.md) or with gcloud services enable (docs/manual-steps.md).

The product and write settings decide which scopes you add here and which scopes auth login requests. Export the settings your MCP client will use (step 5) in the shell you use for steps 3 and 4. Unset means the 15 default products, read-only.

export GOOGLEMCP_PRODUCTS=tasks,calendar,gmail,drive

In the Google Auth Platform console (docs/manual-steps.md):

  1. Branding: app name and your email as support and developer contact.

  2. Audience: user type External, and add your Google account as a test user.

  3. Publishing status: in Testing, Google expires the refresh token 7 days after consent. In production (unverified, personal use) avoids that; see docs/access-longevity.md.

  4. Data access: add the scopes printed by uv run googlemcp scopes.

  5. Clients: create a Desktop app client and download its JSON once.

Because the app is unverified and asks for sensitive and restricted scopes (Gmail, Drive), Google shows a "Google hasn't verified this app" warning at sign-in. You click Advanced, then Go to GoogleMCP (unsafe).

4. Sign in

uv run googlemcp auth login --client-secrets ~/Downloads/client_secret_XXXX.json
uv run googlemcp auth status \
  && uv run python scripts/acceptance/verify_stored_client.py --json ~/Downloads/client_secret_XXXX.json \
  && rm ~/Downloads/client_secret_XXXX.json
uv run googlemcp doctor --probe          # one read-only call per enabled product

auth login stores the client ID, client secret, and refresh token in the OS keyring. The downloaded file is deleted only after the store is confirmed to hold exactly this client; the console never shows the full secret again. To use Google Secret Manager instead, see docs/manual-steps.md.

5. Connect your MCP client

The client starts the server as a child process. Give it the same settings you exported in step 3. For Claude Code:

claude mcp add --env GOOGLEMCP_PRODUCTS=tasks,calendar,gmail,drive \
  --transport stdio googlemcp -- uv run --directory /path/to/googlemcp googlemcp serve

To turn on writes later (for example GOOGLEMCP_WRITE_PRODUCTS=tasks), export the new setting, rerun uv run googlemcp scopes, add the new scopes on the consent screen's Data access page, run uv run googlemcp auth login again, and then add the setting to the client entry.

Claude Desktop, Cursor, Hermes Agent, and a generic JSON entry: docs/clients.md. To check the whole setup end to end, read-only: docs/acceptance.md.

Safety model

  • Local only. googlemcp serve speaks MCP over stdin and stdout and logs to stderr. The only listener is the one-time auth login loopback redirect on 127.0.0.1.

  • Read-only by default. Only read scopes are requested and only read tools are listed until a product is in GOOGLEMCP_WRITE_PRODUCTS.

  • Destructive tools need a second opt-in. Delete, trash, and send tools also need GOOGLEMCP_ALLOW_DESTRUCTIVE=true, and carry the MCP destructiveHint so a client can ask before calling them.

  • Off-by-default products (Meet, Chat, YouTube Reporting, Apps Script) must be listed in GOOGLEMCP_PRODUCTS explicitly.

  • Secrets stay out of the repository and Terraform state. The CLI writes them to the keyring (or another backend); no command prints one. Google error text is passed to the model with URLs and credential-looking values redacted, and withheld entirely for 401 and 403.

  • Prompt injection is a real risk. Email, documents, and calendar entries the model reads can contain instructions. Keep writes off for products you only need to read, and keep your client's tool-approval prompts on.

Threat model and CI scans: docs/security.md. To report a vulnerability, see SECURITY.md.

Access longevity

While the publishing status is Testing, every refresh token expires 7 days after consent. In production, the token lasts until you revoke it, it goes unused for six months, it is displaced by the 100-tokens-per-client limit, or (with Gmail scopes) you change your password. To recover, run uv run googlemcp auth login again. Details: docs/access-longevity.md.

How this compares

  • Google's Workspace MCP servers (docs): remote servers hosted by Google, one per product (Gmail, Drive, Calendar, and other Workspace apps), launched in 2026 and in Developer Preview as of October 2026. You need to join the Workspace Developer Preview Program.

  • taylorwilsdon/google_workspace_mcp: a community Python server for Workspace apps with stdio and HTTP transports, which can also be hosted for several users.

  • GoogleMCP runs only as a local stdio process for one account, covers Google APIs outside Workspace (Tasks, YouTube, Search Console, Analytics, Photos, Apps Script), and starts read-only with per-product write and separate destructive opt-ins. It does not offer a remote or multi-user mode.

ChatGPT custom connectors need a server on public HTTPS, so GoogleMCP does not work there; ChatGPT has its own built-in Google connectors.

Repository layout

catalog/services.json     Product catalog shared by Terraform and the server
infra/terraform/          API enablement, opt-in secret containers, state bucket, tests
src/googlemcp/            Local stdio MCP server: adapters in services/, core, CLI
scripts/                  Inventory generator, offline pre-auth checks, stored-client verifier
tests/                    pytest suite (offline; tests/live runs only with GOOGLEMCP_LIVE=1)
docs/                     Setup, client, and design documentation

Design: docs/architecture.md. Development workflow and checks: docs/development.md. Contributions: CONTRIBUTING.md. Changes: CHANGELOG.md.

License

MIT. See LICENSE.

Available Tools

45 tools
analytics_list_account_summariesanalytics list account summariesB
Read-onlyIdempotent

List GA4 accounts and their properties visible to the user.

Inputs: page_size, page_token. Returns: object

analytics_list_propertiesanalytics list propertiesB
Read-onlyIdempotent

List GA4 properties under an account ('accounts/' or the numeric ID).

Inputs: account (required), page_size, page_token. Returns: object

analytics_run_reportanalytics run reportA
Read-onlyIdempotent

Run a GA4 Data API report.

property_id: numeric ID or 'properties/'. metrics: e.g. ["activeUsers", "sessions"] (max 10). dimensions: e.g. ["date", "country"] (max 9). date_ranges: [{"start_date": "28daysAgo", "end_date": "today"}] (max 4). Returns headers and rows (at most 1000 per call; page with offset).

Inputs: metrics (required), date_ranges (required), property_id (required), limit, +4 more. Returns: object

calendar_get_eventcalendar get eventC
Read-onlyIdempotent

Get one event by id.

Inputs: event_id (required), calendar_id. Returns: object

calendar_list_calendarscalendar list calendarsB
Read-onlyIdempotent

List calendars on the user's calendar list, including 'primary'.

Inputs: page_token, max_results. Returns: object

calendar_list_eventscalendar list eventsA
Read-onlyIdempotent

List events in a time range.

Times are RFC 3339 with an offset, for example 2026-10-05T00:00:00Z.

single_events=true expands recurring events and orders by start time.

Inputs: query, time_max, time_min, page_token, +3 more. Returns: object

calendar_query_freebusycalendar query freebusyB
Read-onlyIdempotent

Return busy intervals for calendars (default: primary) between two RFC 3339 times.

Inputs: time_max (required), time_min (required), time_zone, calendar_ids. Returns: object

docs_get_documentdocs get documentA
Read-onlyIdempotent

Read a Google Doc as plain text with a structure summary.

Text is truncated to max_chars (default 20000, ceiling 100000); truncated reports whether the cap applied.

Inputs: document_id (required), max_chars. Returns: object

driveactivity_query_activitydriveactivity query activityA
Read-onlyIdempotent

Query Drive activity, newest first, for one file (item_id), everything under a folder (folder_id), or the whole Drive (neither).

filter uses the Drive Activity syntax, for example 'time >= "2026-10-01T00:00:00Z" AND detail.action_detail_case:(EDIT RENAME)'. consolidate=true groups related actions.

Inputs: filter, item_id, folder_id, page_token, +2 more. Returns: object

drive_get_filedrive get fileB
Read-onlyIdempotent

Get metadata for one file or folder.

Inputs: file_id (required). Returns: object

drive_read_file_textdrive read file textA
Read-onlyIdempotent

Read the text of a Google Doc, Sheet (first sheet as CSV), Slides deck, or plain-text file. Output is capped at max_chars. Binary files are refused.

Inputs: file_id (required), max_chars. Returns: object

drive_search_filesdrive search filesB
Read-onlyIdempotent

Search the user's Drive. query is optional raw Drive search syntax (for example "fullText contains 'budget'"); name_contains, mime_type and folder_id are safe structured filters. Trashed files are excluded by default.

Inputs: query, order_by, folder_id, mime_type, +4 more. Returns: object

forms_get_formforms get formB
Read-onlyIdempotent

Get a form's title, description, publish state, and question summary.

Inputs: form_id (required). Returns: object

forms_get_responseforms get responseB
Read-onlyIdempotent

Get one form response by id.

Inputs: form_id (required), response_id (required). Returns: object

forms_list_responsesforms list responsesC
Read-onlyIdempotent

List form responses. submitted_after is an RFC 3339 timestamp filter.

Inputs: form_id (required), page_size, page_token, submitted_after. Returns: object

gmail_get_messagegmail get messageA
Read-onlyIdempotent

Get one message: headers, plain-text body (size-capped), and attachment metadata.

Attachment contents are not downloaded.

Inputs: message_id (required), max_body_chars. Returns: object

gmail_get_threadgmail get threadA
Read-onlyIdempotent

Get every message in a thread with headers and size-capped plain-text bodies.

Bodies are capped per message (max_body_chars) and in total across the thread; once the total is spent, later bodies are empty and marked truncated.

Inputs: thread_id (required), max_body_chars. Returns: object

gmail_list_labelsgmail list labelsA
Read-onlyIdempotent

List Gmail labels (system and user labels) with their ids.

Inputs: no named parameters. Returns: object

gmail_search_messagesgmail search messagesA
Read-onlyIdempotent

Search Gmail with Gmail search syntax (for example 'from:alice newer_than:7d').

Returns message ids with From, To, Subject, Date, and snippet when include_headers is true. Use gmail_get_message for the body.

Inputs: query, page_token, max_results, include_headers, +1 more. Returns: object

people_get_personpeople get personB
Read-onlyIdempotent

Get one contact by resource name (for example 'people/c123'), or 'people/me'.

Inputs: resource_name. Returns: object

people_list_connectionspeople list connectionsC
Read-onlyIdempotent

List the user's saved contacts.

Inputs: page_token, sort_order, max_results. Returns: object

people_list_other_contactspeople list other contactsC
Read-onlyIdempotent

List 'Other contacts': addresses Gmail saved automatically from conversations.

Inputs: page_token, max_results. Returns: object

people_search_contactspeople search contactsB
Read-onlyIdempotent

Search the user's contacts by name, email, phone, or organization (prefix match).

Inputs: query (required), max_results. Returns: object

people_search_other_contactspeople search other contactsA
Read-onlyIdempotent

Search 'Other contacts' (auto-saved Gmail correspondents) by name, email, phone.

Inputs: query (required), max_results. Returns: object

photos_create_picker_sessionphotos create picker sessionA
Read-onlyIdempotent

Start a Google Photos Picker session so the user can choose existing photos. Give picker_uri to the user to open; then poll photos_get_picker_session until media_items_set is true.

Inputs: max_item_count. Returns: object

photos_get_picker_sessionphotos get picker sessionA
Read-onlyIdempotent

Check a Picker session. media_items_set becomes true after the user finishes picking. Respect poll_interval between checks.

Inputs: session_id (required). Returns: object

photos_list_app_albumsphotos list app albumsA
Read-onlyIdempotent

List albums created by this app. Albums made in the Photos app or by other apps are not visible (Google API restriction since 2025-03-31).

Inputs: page_size, page_token. Returns: object

photos_list_app_media_itemsphotos list app media itemsA
Read-onlyIdempotent

List media items uploaded by this app, optionally only those in one app-created album. baseUrl values expire after about 60 minutes.

Inputs: album_id, page_size, page_token. Returns: object

photos_list_picked_media_itemsphotos list picked media itemsB
Read-onlyIdempotent

List the items the user picked in a Picker session. baseUrl needs the same OAuth token to download and expires after about 60 minutes.

Inputs: session_id (required), page_size, page_token. Returns: object

searchconsole_inspect_urlsearchconsole inspect urlA
Read-onlyIdempotent

Inspect Google's index status for one URL inside a property. Limited by Google to 2,000 inspections per property per day.

Inputs: url (required), site_url (required), language_code. Returns: object

searchconsole_list_sitessearchconsole list sitesA
Read-onlyIdempotent

List Search Console properties the user can access, with permission level.

Inputs: no named parameters. Returns: object

searchconsole_query_search_analyticssearchconsole query search analyticsA
Read-onlyIdempotent

Query clicks, impressions, CTR, and position for a property.

site_url: 'https://example.com/' or 'sc-domain:example.com'. Dates are YYYY-MM-DD (Pacific time), inclusive. dimensions: any of date, query, page, country, device, searchAppearance. filters: [{"dimension": "query", "operator": "contains", "expression": "mcp"}]. Returns at most 1000 rows per call; page with start_row.

Inputs: end_date (required), site_url (required), start_date (required), filters, +4 more. Returns: object

sheets_get_spreadsheetsheets get spreadsheetA
Read-onlyIdempotent

Get spreadsheet metadata: title, locale, time zone, and its sheets (tabs).

Inputs: spreadsheet_id (required). Returns: object

sheets_read_rangesheets read rangeA
Read-onlyIdempotent

Read cell values from an A1 range (a1_range) such as 'Sheet1!A1:D20'.

Accepts A1 ranges, a sheet title, or a named range. The request is bounded before it is sent: at most max_rows rows (default 200, ceiling 2000) and 52 columns, cell text capped at 1000 characters. truncated, columns_truncated, and cells_truncated report cuts.

Inputs: a1_range (required), spreadsheet_id (required), max_rows, value_render_option. Returns: object

slides_get_presentationslides get presentationB
Read-onlyIdempotent

Summarize a presentation: title and each slide's object id and text.

At most 100 slides and 2000 characters per slide are returned.

Inputs: presentation_id (required). Returns: object

slides_get_thumbnailslides get thumbnailA
Read-onlyIdempotent

Get a PNG thumbnail URL for one slide.

The URL works without sign-in for about 30 minutes and acts as the signed-in user, so do not share it.

Inputs: page_object_id (required), presentation_id (required), size. Returns: object

tasks_get_tasktasks get taskC
Read-onlyIdempotent

Get one task by id.

Inputs: task_id (required), tasklist_id. Returns: object

tasks_list_taskliststasks list tasklistsC
Read-onlyIdempotent

List the user's Google Tasks lists.

Inputs: page_token, max_results. Returns: object

tasks_list_taskstasks list tasksB
Read-onlyIdempotent

List tasks in a task list. Use tasklist_id '@default' for the default list.

show_completed=true also returns tasks completed in Google's apps.

Inputs: page_token, max_results, tasklist_id, show_completed. Returns: object

youtube_analytics_query_reportyoutube analytics query reportA
Read-onlyIdempotent

Query a YouTube Analytics report for the user's channel.

metrics: e.g. ["views", "estimatedMinutesWatched", "likes"]. dimensions: e.g. ["day"] or ["video"] (top videos need sort "-views"). Dates are YYYY-MM-DD and inclusive. filters uses the API syntax, e.g. "video==VIDEO_ID". channel defaults to "channel==MINE". Returns column names and rows (at most 1000).

Inputs: metrics (required), end_date (required), start_date (required), sort, +4 more. Returns: object

youtube_get_videosyoutube get videosA
Read-onlyIdempotent

Get details and statistics for up to 50 videos by ID. Costs 1 quota unit.

Inputs: video_ids (required). Returns: object

youtube_list_my_channelsyoutube list my channelsA
Read-onlyIdempotent

List the YouTube channels owned by the signed-in user. Costs 1 quota unit.

Inputs: no named parameters. Returns: object

youtube_list_my_playlistsyoutube list my playlistsA
Read-onlyIdempotent

List playlists owned by the signed-in user. Costs 1 quota unit per page.

Inputs: page_token, max_results. Returns: object

youtube_list_playlist_itemsyoutube list playlist itemsB
Read-onlyIdempotent

List videos in a playlist. Costs 1 quota unit per page.

Inputs: playlist_id (required), page_token, max_results. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 45 tools

    Disambiguation5/5

    Tools are consistently scoped by Google service and action, with clear distinctions such as search vs get vs list vs query. Overlaps like contacts vs other contacts or app albums vs app media items are explicitly described and unlikely to be confused.

    Naming Consistency5/5

    The set follows a predictable service_verb_noun pattern throughout, e.g. gmail_get_message, calendar_list_events, sheets_read_range. Minor service prefixes like driveactivity and searchconsole are still used consistently within their services.

    Tool Count2/5

    With 45 tools, the surface is very large for an agent to navigate even though it aggregates many Google APIs. The count is justified by breadth, but it still exceeds the practical range for a coherent tool set.

    Completeness3/5

    Read, search, list, and query coverage is broad across Analytics, Gmail, Drive, Calendar, Sheets, YouTube, and others. However, most services lack write/update/delete operations, so common actions like sending email, creating events, or updating sheets would fail.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Multi-account Google MCP server providing read access to Gmail and Calendar via stdio. Supports secure authentication for personal and work accounts with OAuth and keychain token storage.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an MCP client to search, read, label, draft, and send Gmail messages for a single Google account over stdio using your own OAuth client.
      239 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an MCP client to work with a single Google Calendar account using your own OAuth client over stdio: listing calendars and events, free-text search, finding free time across calendars, and creating, updating, or deleting events and answering invitations. Write operations can be gated behind an ask rule and control whether attendees receive Google email notifications.
      13 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an MCP client to search, read, download, create, edit, organize, trash, untrash, and share files in a single Google Drive account over stdio using your own Google OAuth client.
      17
      MIT