How to connect to the Gmail MCP with Claude Code (5 steps)

Developers spend more time in Gmail than they'd like to admit for all of the operationally-relevant context that lives there. 

Deployment alerts, customer-reported bugs, API change notices, access requests, escalations from support. That context is invisible to Claude Code by default, which means your developers either context-switch to find it or work without it.

To help you developers access and send emails from Claude Code, we’ll show you how to connect the AI coding tool with Merge Agent Handler’s Gmail MCP server.

How it works 

Merge Agent Handler sits between Claude Code and Gmail's API. 

You’ll configure a Tool Pack and Registered User in Merge, which generates a unique MCP URL. Claude Code connects to that URL over HTTP and uses an API key (generated in Merge Agent Handler) for authentication. 

Once configured, adding Gmail to a Claude Code session is one command:    

 {
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

From there, every Gmail request your agent makes goes through Merge, which handles OAuth token storage, refresh, and the underlying API calls so none of that lives in your local environment.

Related: The steps for connecting the Google Drive MCP to Claude Code

Prerequisites

Before getting started, you’ll need the following:

• A Merge Agent Handler account
• Claude Code installed
• A Google account with Gmail access 

1. Create a Tool Pack

Log into Merge Agent Handler and navigate to Tool Packs. Create a new pack and give it a relevant name (e.g., Gmail Inbox Agent).

Select Gmail as the connector. 

You can choose which tools to enable. For most development workflows, enabling thread search, message read, and label list covers the common cases. If you want your agent to send emails, draft replies, or apply labels, enable those write tools here as well.

2. Add a Registered User

Inside the Tool Pack, create a Registered User. 

This is the identity context under which your agent operates. The account it acts on behalf of when calling Gmail. Give it a name that maps to your environment, like dev-local or your own name.

Once created, Merge generates a unique MCP URL scoped to this user. You'll use this in step 5.                                                                     

3. Authenticate Gmail

From the Registered User detail page, click Authenticate next to Gmail. This starts a standard Google OAuth flow. 

Sign in with the Google account whose Gmail you want Claude Code to access, and grant the requested permissions.

Merge stores and manages the access token from this point forward, including handling token refresh automatically. You won't need to re-authenticate unless you revoke access or disconnect the account.

Related: How to integrate Slack MCP with Claude Code

4. Gather your credentials

Before configuring Claude Code, collect two things:

1. MCP URL: on the Tool Pack detail page under the Registered User you created. Formatted like https://ah-api.merge.dev/mcp/... 

2. API key: in Settings > API Keys. Create one if you don't have one already

5. Configure Claude Code with the Gmail MCP server

Run this command in your terminal, substituting your actual values:

 {
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

Verify it registered with the command <code class="blog_inline-code">claude mcp list</code>. 

Test the connector and confirm it works with a prompt like  "Find any emails about [project or bug name] from the last week and summarize the key issues raised." 

Gmail MCP FAQ 

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

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

  With Gmail connected, Claude Code can:

• Search threads by keyword or date: find emails about a specific bug report, API issue, or customer escalation without leaving the terminal

• Read message contents: have Claude summarize a thread, extract action items, or pull out specific details like error codes or request IDs

• List labels and folders: browse how incoming mail is organized to scope searches to the right context

• Draft and send emails: compose replies or new messages directly from a Claude Code session (if write tools are enabled in your Tool Pack)

• Cross-reference email context while coding: pull in customer-reported symptoms, alert details, or API change notices without breaking your terminal flow         

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

You can self-host a Gmail MCP server using community packages that wrap the Gmail API directly. For a solo developer on a personal project, that works. 

The friction starts when you're on a team. Each developer needs their own credentials, each environment needs its own token management, and when a token expires or gets revoked, the failure is silent until someone notices the agent stopped working. There's also no visibility into what the agent is actually reading or sending sensitive data.                                                                                                     

Merge Agent Handler addressess all of this by handling credential storage, token refresh, and per-user scoping centrally.

You can see what each Registered User's agent is accessing, revoke access from one place, and scope which labels or threads each agent can reach. For teams running multiple agents against shared Gmail accounts (support inboxes, alert inboxes, team aliases, etc.) that control matters.                                                      

Why connect Gmail to Claude Code?

Gmail is an underrated source of ground truth for developers. Customer bug reports arrive there before they make it into Jira. Vendor API deprecation notices land there weeks before anyone acts on them. On-call escalations, deployment confirmations, and access requests all flow through email, and none of that context is available to Claude Code by default. 

As a result, connecting Gmail via MCP means Claude can treat your inbox as a key data source. You can ask it to find all emails mentioning a specific endpoint, summarize a support thread before jumping into a debugging session, check whether an alert fired during a deployment window, etc., through a single prompt.