Merge Unified's Gmail integration Merge Agent Handler's Gmail MCP server

Connect your AI Agents to Gmail in minutes

Merge lets you securely connect your agents to Gmail and thousands of tools instantly

Start building for free

Read docs

Gmail

Learn more about Merge Agent Handler

Available tools

get_attachment

Download attachment data from a message by attachment ID. Returns binary data (base64url encoded), filename, MIME type, and size.

list_drafts

List all draft messages with pagination. Returns draft references with ID and snippet. Use get_draft for complete details.

get_draft

Retrieve complete details of a specific draft by ID including message content, headers, recipients, and metadata.

create_draft

Create a new draft message with recipients, subject, and body. Supports HTML, CC/BCC, attachments, and threading. Returns draft with ID.

update_draft

Update an existing draft by replacing its content. Completely replaces draft's message content. Returns updated draft.

delete_draft

Permanently delete a draft. Cannot be undone. Draft and content are permanently removed.

send_draft

Send an existing draft immediately. Draft is sent as email and automatically deleted from drafts. Returns sent message with ID.

list_labels

List all labels including system and custom labels. Returns name, type, visibility, message counts, and colors.

get_label

Retrieve detailed information about a specific label by ID including name, type, visibility, message counts, and colors.

create_label

Create a new custom label for organizing messages. Specify name, visibility settings, and optional colors. Returns created label with ID.

update_label

Update an existing label's properties including name, visibility, and colors. Cannot modify system labels, only custom labels.

delete_label

Permanently delete a custom label. Removes label from all messages. Cannot delete system labels. Cannot be undone.

list_messages

List messages with search, filtering, and pagination. Supports Gmail query syntax (from:, to:, subject:, is:unread, etc.). Returns message references only.

get_message

Retrieve complete message details by ID including headers, body, attachments, labels, and metadata. Format options control detail level.

send_message

Send a new email with recipients, subject, and body. Supports HTML, CC/BCC, attachments, and threading. Returns sent message with ID and thread ID.

modify_message_labels

Add or remove labels from a message. Supports up to 100 label additions/removals per operation. Use system or custom label IDs.

delete_message

Move message to TRASH (soft delete). Recoverable for 30 days. Message gets TRASH label and is removed from other folders.

batch_delete_messages

Move multiple messages to trash in a single batch operation. More efficient than individual deletes.

batch_modify_messages

Modify labels on multiple messages in a batch operation. Supports up to 100 label additions/removals. More efficient than individual modifications.

list_threads

List conversation threads with search, filtering, and pagination. Supports Gmail query syntax. Returns thread references with ID and snippet.

get_thread

Retrieve a complete conversation thread by ID including all messages in chronological order. Format options control detail level.

modify_thread_labels

Add or remove labels from all messages in a thread simultaneously. Supports up to 100 label additions/removals. More efficient than modifying individual messages.

delete_thread

Move all messages in a thread to TRASH (soft delete). Recoverable for 30 days. More efficient than deleting individual messages.

validate_credential

Validate Gmail credentials. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Gmail MCP server

How can I use the Gmail MCP server?

The use cases naturally vary depending on your agent, but here are a few agentic workflows from using this email MCP server:

Inbox management: Your agent can read and/or send emails on the user’s behalf. For example, it can find specific messages, draft replies, and present it to a user

Background tasks: Your agent can periodically scan inboxes, monitor for alerts, extract structured information from emails, and/or flag anomalies

Support tickets: Your agent can detect support-related emails and trigger actions across your integrated tools. For instance, it can create a Jira ticket and auto-fill fields like the issue summary using the email’s content

Email sends: Your agent can interact with users in the application they already work from (e.g., Slack) and based on the conversations, propose relevant emails and deliver them once approved

What are popular tools for Gmail’s MCP server?

Here are some popular tools across data categories:

Draft management

<code class="blog_inline-code">send_draft</code>
<code class="blog_inline-code">list_drafts</code>
<code class="blog_inline-code">get_drafts</code>
<code class="blog_inline-code">create_draft</code>
<code class="blog_inline-code">update_draft</code>

Label/folder management

<code class="blog_inline-code">modify_message_labels</code>
<code class="blog_inline-code">batch_modify_messages</code>
<code class="blog_inline-code">modify_thread_labels</code>
<code class="blog_inline-code">get_labels</code>

Email delivery

<code class="blog_inline-code">get_message</code>
<code class="blog_inline-code">send_message</code>
<code class="blog_inline-code">list_messages</code>

What makes Merge Agent Handler’s Gmail MCP server better than alternative Gmail MCP servers?

Here are just a few advantages of using Merge Agent Handler’s Gmail MCP server:

Enterprise-grade authentication and credential handling. Agent Handler manages all auth flows (including dynamic and platform-specific onboarding), reducing integration risk and maintenance

Security gateway and DLP. Every tool request and response is scanned for sensitive data, and rules can block, redact, or mask fields. This prevents misconfigured Gmail actions from allowing data exposure

Real-time observability and searchable logs. Agent Handler logs every tool call and underlying API request, enabling full audit trails and searchable debugging

Connector Studio for customization. Teams can modify or create Gmail tools without writing a single line of code

How can I add Gmail’s MCP server tools to a Tool Pack?

You can take the following steps:

1. Navigate to Tool Packs in the Agent Handler dashboard sidebar.

2. Create a new Tool Pack by clicking "Add New" or select an existing Tool Pack you want to modify.

3. Add the Gmail connector from the available connectors list. You can also choose the specific tools you want to enable.

4. Configure your agent’s authentication method by either selecting individual authentication (each user would provide their own Gmail credentials) or shared authentication: (organization-level access by using a single set of credentials)

5. Save your Tool Pack. From there, the Gmail tools are now available for your agents to use within the Tool Pack!

Can I set custom security rules for Gmail tool calls with Merge Agent Handler?

Yes, you can add any number of security rules in a matter of clicks in Merge Agent Handler.

For example, you can:

Block credit card numbers in emails
Redact social security numbers in email content
Log when agents share email addresses
Block your agents from accessing emails that contain specific terms, like "confidential" or "internal only"

Explore other MCP servers built and managed by Merge

Peec AI

Pipedrive

PostHog

PubMed

Pylon

Quartr

QuickBooks Online

Ramp

ReadMe

Rootly

Sabre

Salesforce

Sanity

SAP SuccessFactors

SendGrid

Sentry

ServiceNow

SharePoint

Shopify

Slack

Smartsheet

Snowflake

Spotify

Square

Ready to try it out?

Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now