Gmail MCP Server Cursor IDE Setup 2026

How do you set up a Gmail MCP server in Cursor? There's no first-party Gmail server from Google the way there is for GitHub or GitLab, so you install a community server, create your own OAuth client in Google Cloud Console, authorize once in a browser, and point Cursor's mcp.json at the resulting credentials. The most widely used option is @gongrzhe/server-gmail-autoauth-mcp, run through npx, storing tokens under ~/.gmail-mcp/.

This matters more for Gmail than for most MCP servers because there is no single official vendor path. You are choosing between a self-hosted open-source server with your own Google Cloud project, or a vendor-hosted connector that manages OAuth for you. This guide covers the self-hosted route in full, since it's the one you can audit, and flags where a hosted alternative changes the picture.

If you actually want Google Calendar or Google Drive instead of Gmail specifically, those have their own dedicated guides linked at the bottom — Google ships each as a separate integration surface, and a server built for one doesn't cover the others.

Why Gmail MCP setup looks different from GitHub, Slack, or Linear

Three things make this one messier than the vendor-hosted servers elsewhere on this site.

There's no single canonical maintainer. GitHub publishes and supports github/github-mcp-server. Gmail has several community servers of varying quality and maintenance status, built against the same Gmail API but with different tool names, different scopes, and different setups. Picking one is part of the job here, not a footnote.

You provide your own OAuth app. Google doesn't hand out a pre-registered client ID for third-party MCP servers to use against your inbox — you create a Google Cloud project, enable the Gmail API on it, and generate your own OAuth 2.0 Desktop app credentials. That's more setup than a server that ships with a baked-in app, but it also means the OAuth consent screen a reviewer sees is yours, not a shared community app with an uncertain audit trail.

Maintenance churn is real. Several Gmail MCP servers have been archived or gone quiet after their maintainer moved on, including at least one with well over a thousand GitHub stars. Before you commit to a specific package, check its commit history and open-issue count, not just its star count — stars accumulate long after a project stops getting fixes.

Prerequisites

Step 1: Create a Google Cloud project and enable the Gmail API

1. Go to Google Cloud Console and create a new project, or pick an existing one you're comfortable granting Gmail access from.
2. Open APIs & Services → Library, search for Gmail API, and enable it for that project.
3. Open APIs & Services → OAuth consent screen. Set the user type to External unless you're on Workspace and restricting it internally. Fill in the required app name and support email fields.
4. Under Test users, add the Gmail address you'll actually be authorizing. While the app is in testing mode (the default, and fine for personal use), only listed test users can complete the OAuth flow.

Step 2: Create OAuth 2.0 credentials

1. APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Desktop app. This matters — a Web application type expects a different redirect flow and won't match what the local server expects.
3. Create it, then download the JSON credentials file. Google names it something like client_secret_XXXX.json.
4. Rename the downloaded file to gcp-oauth.keys.json.

Step 3: Install and authorize the server

Create the config directory the server expects and move your credentials there:

mkdir -p ~/.gmail-mcp
mv ~/Downloads/gcp-oauth.keys.json ~/.gmail-mcp/

Run the one-time auth flow:

npx @gongrzhe/server-gmail-autoauth-mcp auth

This opens your default browser to the Google consent screen. After you approve it, the tool writes a credentials.json file into the same ~/.gmail-mcp/ directory and the local callback server (listening on localhost:3000 during this step) shuts down. From this point on, the server authenticates using the stored credentials — you don't repeat the browser flow on every Cursor restart.

Step 4: Add the Cursor mcp.json block

Cursor merges MCP config from two files, with the project-level one winning on a name collision:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
    }
  }
}

No token or env block is required in this file — the credentials the server needs already live in ~/.gmail-mcp/credentials.json from Step 3, and the package reads from there automatically regardless of which directory Cursor launches it from. Save the file and restart Cursor. Check Settings → Tools & Integrations → MCP Tools for a green status next to gmail.

Step 5: Verify

In a new Cursor chat:

Search my inbox for unread emails from the last 3 days and summarize the senders and subjects.

A real, specific answer confirms the connection and read scope both work. If you plan to draft or send mail from Cursor, test that separately and read the write-tool list below first — don't discover what a write tool does by watching it run against your real inbox.

What this server can and can't do

The @gongrzhe/server-gmail-autoauth-mcp package exposes upwards of a dozen tools, more than a read-only doc-fetch server like Context7 or a scoped issue tracker like Linear. The ones worth knowing before you start prompting:

Cursor prompts for approval before running write tools by default, the same as every other MCP server. Read the specific arguments before approving delete_email or any batch variant — approving once doesn't mean you've reviewed what it's about to touch.

Scoping down: read-only is worth it here more than most servers

Because Gmail write tools include permanent deletion and outbound sending, a read-only setup is a reasonable default for anyone using the agent primarily to search and summarize rather than to triage and act. There's no documented single environment variable that flips this server to a hard read-only mode the way Linear's or GitHub's official servers support — the practical equivalent is authorizing the OAuth consent screen with only the gmail.readonly scope instead of the broader scopes the default setup requests, which means going back into the Google Cloud OAuth consent screen configuration and trimming the requested scopes before you run the auth step. If the server you chose doesn't make that scope trim easy, treat "always read the write-tool arguments before approving" as the actual control, not a checkbox.

The vendor-hosted alternative

If you'd rather not run and maintain a local server or manage your own Google Cloud OAuth app, hosted connector platforms (Composio is one example that publishes a documented Cursor integration path) manage the OAuth app and token refresh for you and expose Gmail tools through their own MCP endpoint. That trades local control and auditability for less setup — reasonable for a quick personal integration, less so if you need to know exactly which scopes a shared OAuth app is requesting against your account.

Troubleshooting

Server never appears in Cursor. Confirm the file is ~/.cursor/mcp.json or .cursor/mcp.json, the top-level key is mcpServers, and the JSON is valid — one syntax error anywhere in the file drops every server it defines, not just Gmail.

auth command fails or the browser never opens. Confirm nothing else is bound to localhost:3000 — the one-time OAuth callback listens there. Close other local dev servers on that port and retry.

"Access blocked: this app's request is invalid" on the consent screen. Usually means the OAuth client type is wrong. Confirm you created a Desktop app credential, not a Web application one, in Step 2.

"App isn't verified" warning during consent. Expected while your OAuth consent screen is in testing mode with a personal or small-team app — click through the warning as the account you added under Test users. This is a Google review-status message, not a broken config.

Server connects but every call fails with a permissions error. The Gmail account that ran npx @gongrzhe/server-gmail-autoauth-mcp auth isn't the account you're now querying, or you re-authorized with a narrower scope than the tool you're calling needs. Delete ~/.gmail-mcp/credentials.json and re-run auth to get a clean token.

Tool exists but does nothing on Workspace accounts. A Workspace admin may have restricted third-party OAuth app authorization at the domain level. That's an admin-console setting, not a bug in your mcp.json.

Frequently Asked Questions

Is there an official Gmail MCP server from Google? No. Unlike GitHub or GitLab, Google has not published a first-party Gmail MCP server as of this writing. Every option is community-maintained or vendor-hosted on top of the standard Gmail API.

Does this need my Gmail password? No. The OAuth flow never touches your password — you authorize a scoped grant through Google's own consent screen, and the server stores a refresh token, not a credential.

Can Cursor send email without my approval? Not by default. Cursor's standard approval flow prompts before running write tools including send_email, unless you've changed the approval mode to auto-run MCP tools.

What happens if the package I chose stops being maintained? Check the repository's recent commit activity before adopting one — a high star count with no commits in the last year is a signal to look at an actively maintained alternative rather than assume abandoned code is still safe to run against your live inbox.

Do I need a Google Workspace account, or does personal Gmail work? Personal Gmail works. Workspace accounts may need an admin to allow the OAuth consent screen to reach external apps, depending on the organization's security policy.

Related guides

Official docs cited