From c561f58bd56efd5da2fe7059563f1d18590ceb6d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 13:55:43 +0000 Subject: [PATCH] docs(gmail): note gmail.settings.basic for filter tools create_filter/list_filters 403 after upscoping because Cursor's first-party Google OAuth client never requests https://www.googleapis.com/auth/gmail.settings.basic. This plugin is a URL wrapper around gmailmcp.googleapis.com and cannot declare that scope (no CLIENT_ID in mcp.json). Document the gap and that existing users must re-consent after the connector client is updated. Fixes investigation for cursor/plugins#385; the OAuth client change is outside this repo. Co-authored-by: Lutz Schwemer Panchez --- third_party/gmail/.cursor-plugin/plugin.json | 2 +- third_party/gmail/CHANGELOG.md | 6 ++++++ third_party/gmail/README.md | 14 ++++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/third_party/gmail/.cursor-plugin/plugin.json b/third_party/gmail/.cursor-plugin/plugin.json index 32279d3b7..8e1cea8e7 100644 --- a/third_party/gmail/.cursor-plugin/plugin.json +++ b/third_party/gmail/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gmail", "displayName": "Gmail", - "version": "1.0.0", + "version": "1.0.1", "minClientVersions": { "cursor": "3.13.0" }, diff --git a/third_party/gmail/CHANGELOG.md b/third_party/gmail/CHANGELOG.md index fa3730d37..b3a56cbcd 100644 --- a/third_party/gmail/CHANGELOG.md +++ b/third_party/gmail/CHANGELOG.md @@ -2,6 +2,12 @@ All notable changes to this plugin will be documented here. +## 1.0.1 — filter tools OAuth note + +- Documented that `create_filter` / `list_filters` (and related filter tools) need `https://www.googleapis.com/auth/gmail.settings.basic`. +- This plugin still does not declare OAuth scopes: Google Workspace sign-in uses Cursor's first-party client against `https://gmailmcp.googleapis.com/mcp/v1`. +- After that scope is added to the connector OAuth client, existing installs must disconnect Gmail and sign in again. + ## 1.0.0 — initial release - Logo: official Gmail 2026 product icon from Google productlogos, on a padded white tile. diff --git a/third_party/gmail/README.md b/third_party/gmail/README.md index bfe2f2799..549902074 100644 --- a/third_party/gmail/README.md +++ b/third_party/gmail/README.md @@ -27,6 +27,20 @@ Or run `/add-plugin gmail` in chat. Auth is OAuth 2.0 against Google. Cursor prompts for Google sign-in when the plugin connects. +This plugin does **not** declare OAuth scopes or a Google client ID. Unlike the X plugin, Google Workspace connectors use Cursor's first-party Google OAuth client against the hosted MCP. Scopes are not configured in this repository. + +### Filter tools + +`create_filter`, `list_filters`, `update_filter`, and `delete_filter` require: + +`https://www.googleapis.com/auth/gmail.settings.basic` + +That is a different grant from `gmail.modify` (labels/messages) and from “See (but not change) your email settings” (`gmail.readonly`). Google's hosted MCP already advertises `gmail.settings.basic` in its protected-resource metadata, but the connector OAuth client must request it or filter tools return **403 after trying upscoping**. + +After that scope is added to Cursor's Google OAuth client / consent screen, **existing users must disconnect Gmail and sign in again** so Google can re-prompt. Re-auth without a new scope does nothing. + +Until then, create filters in Gmail Settings → Filters and Blocked Addresses. + ## Docs - Google MCP setup: https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server