Gmail plugin: create_filter / list_filters fail with 403 — OAuth missing gmail.settings.basic

Summary

The Gmail connector exposes create_filter, list_filters (and related filter tools), but calling them fails with 403 after trying upscoping. Google Account → Linked Apps shows the Cursor/Grok app only has “See (but not change) your email settings”, so filter create/list cannot work. Re-auth does not help: Google never requests a settings-write scope during consent.

Environment

Product: Grok Bot / Cursor Gmail MCP connector
Plugin id (from install): 45893410
MCP server id: user-Gmail--shark5060-gmail-com
Account: personal Gmail (example: shark5060@gmail.com)
Other Gmail tools work: list_labels, search_threads, label apply, etc.

Steps to reproduce

Install/connect the Gmail plugin and complete OAuth.
Confirm mail tools work (e.g. list_labels, search_threads).
Call list_filters or create_filter (e.g. criteria from: youtube.com, action add a user label + remove INBOX).
Optionally force re-auth (AuthenticateMcpServer with force_reauth) and approve all consent screens again.
Retry create_filter / list_filters.

Expected

Filter tools succeed, or
OAuth consent requests https://www.googleapis.com/auth/gmail.settings.basic so Linked Apps shows edit/create/change settings & filters, then tools work after re-consent.

Actual

Tool call error (approx.): HTTP MCP tool execution failed: … Server returned 403 after trying upscoping
Google Linked Apps for the Cursor app under Gmail includes wording like:
- See (but not change) your email settings
- View your settings (e.g., filters and labels)
There is no Linked Apps toggle to grant settings write; only delete connection.
Label create/update and message labeling still work (consistent with gmail.modify, not settings write).

Why this matters

Without users.settings.filters.*, agents cannot install durable server-side routing (skip Inbox + apply label) and must re-label mail after arrival. The tools being present implies filter management is intended.

API / scope note

Per Gmail API users.settings.filters.create, create requires:

https://www.googleapis.com/auth/gmail.settings.basic

(Gmail scopes: that scope is “See, edit, create, or change your email settings and filters in Gmail.”)

gmail.modify covers labels/messages but not filter settings write — matching the Linked Apps “see but not change” text.

Suggested fix

Add gmail.settings.basic to the Gmail plugin OAuth client / consent scope list.
Document that existing users must re-consent after the scope is added.
Ensure upscoping actually requests that scope (current “403 after trying upscoping” suggests upscope does not obtain write settings).

Workaround

Create filters manually (or via browser automation) in Gmail Settings → Filters and Blocked Addresses until the connector requests the correct scope.

Related (third-party, not Cursor)

Other Gmail MCP projects have discussed the same scope requirement, e.g. needing gmail.settings.basic for filter tools — same underlying Google API constraint.

confirmed this working by adding my own google OAuth Client as a custom MCP:

    "gmail": {
      "type": "http",
      "url": "https://gmailmcp.googleapis.com/mcp/v1",
      "auth": {
        "CLIENT_ID": "asdf",
        "CLIENT_SECRET": "1234",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly",
          "https://www.googleapis.com/auth/gmail.modify",
          "https://www.googleapis.com/auth/gmail.compose",
          "https://www.googleapis.com/auth/gmail.settings.basic"
        ]
      }
    }

@iShark5060

@iShark5060 Can I work on this?

@iShark5060 Can I work on this?

i mean, feel free.
I have got it working with my own OAuth Client + custom MCP, but since some of the scopes requires a Workspace account that is enrolled in https://developers.google.com/workspace/preview this might not be feasible for many people.

@iShark5060

Hey @iShark5060, thanks for the thorough report, and your diagnosis is exactly right. The Gmail plugin talks to Google's hosted Gmail MCP, and the OAuth consent Cursor requests for it is pinned to gmail.readonly, gmail.modify and gmail.compose. gmail.settings.basic isn't in that set, and a reconnect or token refresh can't add a scope, so create_filter / list_filters are offered by Google's server but can only come back 403. That's why re-auth did nothing and why your own OAuth client with the extra scope works.

Adding the scope on our side isn't a one-line change: it's a sensitive scope, so Google has to verify the app for it first, otherwise every Gmail consent gets blocked. That's the part being worked through internally, together with hiding the filter tools (or returning a clear "not authorized for filters, reconnecting won't help") until it lands. I've attached this issue to the tracking ticket. No ETA I can give; your custom-client setup remains the working path for now, with the Workspace preview caveat you mentioned.

@goodchanges, appreciate the offer, but there's nothing in this repo to change; the scope set lives in Cursor's OAuth configuration, not in the plugin's mcp.json.

@deanrie

Hi @deanrie, thanks for the thorough reply. I understand that the app has to be verified for it to work, especially since you are using it in prod, and not as a "test" project like I am.

I'll be patient.

Navigation Menu

Repository navigation

Gmail plugin: create_filter / list_filters fail with 403 — OAuth missing gmail.settings.basic #385

Summary

Environment

Steps to reproduce

Expected

Actual

Why this matters

API / scope note

Suggested fix

Workaround

Related (third-party, not Cursor)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Gmail plugin: create_filter / list_filters fail with 403 — OAuth missing gmail.settings.basic #385

Description

Summary

Environment

Steps to reproduce

Expected

Actual

Why this matters

API / scope note

Suggested fix

Workaround

Related (third-party, not Cursor)

Activity

iShark5060 commented on Sep 16, 2026

goodchanges commented on Sep 25, 2026

iShark5060 commented on Sep 25, 2026

deanrie commented on Oct 5, 2026

iShark5060 commented on Oct 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions