How to connect a Gmail MCP to Cursor (4 steps)

Developers writing Gmail integrations spend most of their time in Cursor, but the data they need to understand is in Gmail.

Before you can write a message parser, you need to know what a real message object looks like. Before you can implement thread traversal, you need to understand how Gmail structures reply chains. Before you add label filtering, you need to see the actual label IDs your integration will receive, and the list goes on.

Every one of those lookups means leaving Cursor, making a manual API call or navigating Gmail's API explorer, and returning to the editor with the answer in a separate browser tab.

To help your developers easily query Gmail data without leaving Cursor, we'll show you how to connect Gmail with Merge Agent Handler's Gmail MCP server.

How it works

Merge Agent Handler connects Cursor to Gmail's API through the Merge CLI.

Install the CLI, authenticate once, and run a single setup command from the project root.

That command writes a ## Merge CLI section to your project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach Gmail.

Once connected, Merge manages Gmail OAuth token storage and refresh on your behalf, so no credential state lives in your local environment.

Here's the command that registers the connection:

merge setup cursor

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Google account with Gmail access

If you want to connect Merge Agent Handler's Gmail MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Add the Merge CLI to your environment with pipx: pipx install merge-api

Confirm the installation succeeded: merge --version

Related: How to use a Gmail MCP in Claude Code

2. Log in to Merge

Connect the CLI to your Merge Agent Handler account: merge login

This links the CLI to your account so Merge can make authorized requests against Gmail on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools: merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, safe to re-run if you need to reset.

4. Authenticate Gmail

Open a Cursor chat in your project.

Submit a command to validate the connection and get immediate value while writing integration code. It can be something like "Fetch a real message object from my inbox and show me the full response structure, including all headers, body parts, and MIME types, so I can write the parsing logic correctly."

The first time you invoke a Gmail tool, a Magic Link will appear to complete connector authentication.

‍

{{this-blog-only-cta}}

Gmail MCP FAQ

In case you have more questions on setting up and using the Gmail MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the Gmail MCP is connected to Cursor?

With Gmail connected, Cursor can:

• Inspect the full message response shape before writing parsers: retrieve a real message object with all headers, payload parts, and MIME type breakdowns so your parsing code handles the actual structure, not a simplified version from the docs

• Fetch thread structures to understand reply chain layout: pull a real thread to see how Gmail nests messages, which IDs link replies together, and how the API paginates long threads before you write traversal logic

• Look up label IDs for accurate filter logic: retrieve the exact label ID strings your integration needs for filtering and categorization so you never hardcode display names that don't match API values

• Check which OAuth scopes a given operation requires: query what scopes are in effect and what operations are available under the connected credential before writing the OAuth scope request in your integration's auth flow

• Validate pagination behavior on a real inbox: pull a large inbox listing to see how nextPageToken is returned and structured in a real response before implementing your pagination handler

Why use Merge Agent Handler vs. a self-hosted Gmail MCP server?

You can self-host a Gmail MCP server using open-source packages that wrap the Gmail API directly. For a solo developer working against their own Google account, that setup works: create a Google Cloud project, configure OAuth credentials, stand up the server, and point Cursor at it.

The overhead compounds at the team level.

Gmail OAuth requires a Google Cloud project with the Gmail API enabled, correctly scoped credentials, and token refresh logic that survives process restarts. If multiple developers need Gmail access through Cursor, each manages their own credentials or tokens get shared in ways that are difficult to audit and revoke cleanly.

Merge Agent Handler centralizes authentication and lets you define which Gmail operations each agent is allowed to perform. Merge then enforces those boundaries and logs every tool call with a full audit trail, including the full input and output.

Why connect Gmail to Cursor?

Developers writing Gmail integrations have to understand the API's data model before they can write correct code against it.

Gmail uses a layered message structure: messages contain a payload, payloads have parts, parts may themselves have nested parts, body content is base64-encoded, and headers like Content-Type and MIME-Version determine how to decode each piece.

That structure is documented, but reading documentation is not the same as seeing a real message object from the account your integration will run against.

With the Gmail MCP connected, Cursor can pull real message data directly in the chat panel. You can fetch a message while writing the parser that will process it, retrieve a thread while writing the traversal function, or look up label IDs while writing the filter predicate.

This also applies to auth setup. Before wiring up Gmail OAuth in your integration, you can ask Cursor which scopes are available and what operations they gate. That reference is more reliable than documentation when you're working against a specific credential and need to know exactly what your agent can and cannot do.