GoogleMCP
Provides tools for accessing Gmail messages and threads, with read-only access by default and write/send operations requiring opt-in.
Provides tools for accessing Google Analytics data and reporting capabilities.
Allows reading and managing Google Calendar calendars and events, with write operations requiring opt-in.
Provides Google Chat integration for Workspace accounts, with read-only access by default and writes requiring opt-in.
Allows reading and editing Google Docs documents, with write access requiring opt-in.
Provides tools for accessing and managing Google Drive files and folders, with writes and destructive actions requiring separate opt-ins.
Provides tools for interacting with Google Forms forms and responses.
Provides access to the Google Meet REST API for Google Workspace accounts.
Provides access to Google Photos app-created Library data and photos selected through the Picker API.
Allows reading and editing Google Sheets spreadsheets, with write access requiring opt-in.
Allows reading and editing Google Slides presentations, with write access requiring opt-in.
Provides tools for managing Google Tasks task lists and tasks, with write operations requiring opt-in.
Provides tools for the YouTube Data API, with read-only access by default and writes requiring opt-in.
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., "@GoogleMCP what's on my calendar tomorrow, and any unread emails from today?"
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.
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 |
| Google Tasks | on | |
| Gmail | on | |
| Google Calendar | on | |
| Google Drive | on | |
| Google Docs | on | |
| Google Sheets | on | |
| Google Slides | on | |
| Google Forms | on | |
| People and Contacts | on | |
| Google Meet | off | Meet REST API needs a Google Workspace account |
| Drive Activity | on | |
| Google Chat | off | Needs a Business or Enterprise Workspace account and a Chat app configured in the console |
| YouTube Data | on | |
| YouTube Analytics | on | |
| YouTube Reporting | off | Reporting jobs are created and kept on Google's side |
| Google Analytics | on | |
| Search Console | on | |
| Apps Script | off | Can run code in your account; also needs a manual per-user setting |
| 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 callOr run it without a checkout (not published on PyPI):
uvx --from git+https://github.com/1solomonwakhungu/googlemcp googlemcp productsThe 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_IDThen enable the APIs for the products you want, either with Terraform
(docs/terraform.md) or with gcloud services enable
(docs/manual-steps.md).
3. Configure the consent screen and create a Desktop OAuth client
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,driveIn the Google Auth Platform console (docs/manual-steps.md):
Branding: app name and your email as support and developer contact.
Audience: user type External, and add your Google account as a test user.
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.
Data access: add the scopes printed by
uv run googlemcp scopes.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 productauth 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 serveTo 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 servespeaks MCP over stdin and stdout and logs to stderr. The only listener is the one-timeauth loginloopback 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 MCPdestructiveHintso a client can ask before calling them.Off-by-default products (Meet, Chat, YouTube Reporting, Apps Script) must be listed in
GOOGLEMCP_PRODUCTSexplicitly.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 documentationDesign: docs/architecture.md. Development workflow and checks: docs/development.md. Contributions: CONTRIBUTING.md. Changes: CHANGELOG.md.
License
MIT. See LICENSE.
Available Tools
45 toolsanalytics_list_account_summariesanalytics list account summariesBRead-onlyIdempotent
List GA4 accounts and their properties visible to the user.
Inputs: page_size, page_token. Returns: object
analytics_list_propertiesanalytics list propertiesBRead-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 reportARead-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 eventCRead-onlyIdempotent
Get one event by id.
Inputs: event_id (required), calendar_id. Returns: object
calendar_list_calendarscalendar list calendarsBRead-onlyIdempotent
List calendars on the user's calendar list, including 'primary'.
Inputs: page_token, max_results. Returns: object
calendar_list_eventscalendar list eventsARead-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 freebusyBRead-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 documentARead-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 activityARead-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 fileBRead-onlyIdempotent
Get metadata for one file or folder.
Inputs: file_id (required). Returns: object
drive_read_file_textdrive read file textARead-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 filesBRead-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 formBRead-onlyIdempotent
Get a form's title, description, publish state, and question summary.
Inputs: form_id (required). Returns: object
forms_get_responseforms get responseBRead-onlyIdempotent
Get one form response by id.
Inputs: form_id (required), response_id (required). Returns: object
forms_list_responsesforms list responsesCRead-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 messageARead-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 threadARead-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 labelsARead-onlyIdempotent
List Gmail labels (system and user labels) with their ids.
Inputs: no named parameters. Returns: object
gmail_search_messagesgmail search messagesARead-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 personBRead-onlyIdempotent
Get one contact by resource name (for example 'people/c123'), or 'people/me'.
Inputs: resource_name. Returns: object
people_list_connectionspeople list connectionsCRead-onlyIdempotent
List the user's saved contacts.
Inputs: page_token, sort_order, max_results. Returns: object
people_list_other_contactspeople list other contactsCRead-onlyIdempotent
List 'Other contacts': addresses Gmail saved automatically from conversations.
Inputs: page_token, max_results. Returns: object
people_search_contactspeople search contactsBRead-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 contactsARead-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 sessionARead-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 sessionARead-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 albumsARead-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 itemsARead-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 itemsBRead-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 urlARead-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 sitesARead-onlyIdempotent
List Search Console properties the user can access, with permission level.
Inputs: no named parameters. Returns: object
searchconsole_query_search_analyticssearchconsole query search analyticsARead-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 spreadsheetARead-onlyIdempotent
Get spreadsheet metadata: title, locale, time zone, and its sheets (tabs).
Inputs: spreadsheet_id (required). Returns: object
sheets_read_rangesheets read rangeARead-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 presentationBRead-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 thumbnailARead-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 taskCRead-onlyIdempotent
Get one task by id.
Inputs: task_id (required), tasklist_id. Returns: object
tasks_list_taskliststasks list tasklistsCRead-onlyIdempotent
List the user's Google Tasks lists.
Inputs: page_token, max_results. Returns: object
tasks_list_taskstasks list tasksBRead-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 reportARead-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 videosARead-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 channelsARead-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 playlistsARead-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 itemsBRead-onlyIdempotent
List videos in a playlist. Costs 1 quota unit per page.
Inputs: playlist_id (required), page_token, max_results. Returns: object
youtube_searchyoutube searchARead-onlyIdempotent
Search YouTube. EXPENSIVE: each call costs 100 quota units (1% of the
default daily quota). At most 25 results per call and 20 calls per
server process. Prefer the list tools when possible. for_mine
restricts results to the user's own videos (kind must be 'video').
Inputs: query (required), kind, order, for_mine, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
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.
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.
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.
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
Related MCP Connectors
Your Gmail, Calendar, Drive, GitHub, Oura, wallet and confirmed profile facts in any MCP client.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Related MCP Servers
- AlicenseBqualityCmaintenanceMulti-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.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- AlicenseAqualityCmaintenanceEnables 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.17MIT