Connect your AI Agents to Gmail in minutes
Available tools
get_attachment
Download an attachment from a message by attachment ID. Returns readable extractedtext for PDF, DOCX, and text files (use this to read the contents, e.g. a resume), plus the raw base64url data, filename, MIME type, and size. Check extractionstatus for the outcome.
list_drafts
List draft messages, newest first, with pagination. Pass q to filter server-side with Gmail search syntax (e.g. 'subject:invoice'). Each result includes draft/message/thread IDs plus to, cc, subject, and snippet inline; set includemetadata=false for bare IDs. Use getdraft only when the full body or attachments are needed.
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 identifiers only: the subject, recipients and body are not echoed back, which is not a sign the draft is empty -- use getdraft to read it back. To set fromaddress, first call listsendas_addresses to get a verified alias.
update_draft
Edit an existing draft. Only the fields you supply change; everything else (recipients, subject, body, attachments, thread) is preserved. Pass an empty list to clear recipients or attachments. The draft ID is stable but the underlying message ID changes on every update. Use listdrafts for draft IDs and listsendasaddresses for a valid from_address.
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, both system and custom. Returns id, name, type and visibility only. Use get_label for a single label's message and thread totals, which this endpoint does not return.
get_label
Retrieve detailed information about a specific label by ID including name, type, visibility, message counts, and colors.
create_label
Create a custom label. Nest it by putting slashes in the name, e.g. 'Clients/Acme' creates Acme under Clients. Visibility defaults to shown. Colors must come from Gmail's fixed palette. Returns the new label with its 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
Search or list messages with Gmail query syntax (from:, subject:, is:unread, newerthan:, OR, -negation) and pagination. Results carry sender, to, cc, subject, date, snippet, labels, and Message-ID inline, so triage and replies need no follow-up call. An empty list with searchscope.complete means no such message exists; empty searches retry across spam/trash. Read bodies with getmessagetext.
get_message
Retrieve complete message details by ID including the raw MIME tree, all headers, base64-encoded body parts, attachments, and labels. Format options control detail level. To just read or summarize the body, use getmessagetext instead: it returns decoded text and is far smaller.
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. To reply, pass threadid and use messageidheader from listmessages as inreplyto. To set fromaddress, first call listsendasaddresses: Gmail rewrites From: to the default address if the alias is not verified.
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 a message to trash by adding the TRASH label. Other labels such as INBOX and SENT are left in place. Not a permanent delete: use untrashmessage to restore it, or find trashed mail with listmessages and q='in:trash'.
untrash_message
Restore a message from trash by removing the TRASH label. Its other labels are untouched, so it returns to the folders it was in. Use list_messages with q='in:trash' to find trashed message IDs. Safe to repeat: a message already out of trash is unchanged.
batch_delete_messages
Move multiple messages to trash in one batch by adding the TRASH label to each. Other labels are left in place. Not a permanent delete: restore them one at a time with untrashmessage. Use listmessages to find message IDs.
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_send_as_addresses
List the addresses this mailbox can send mail as, including aliases and delegated addresses. Call this before setting fromaddress on sendmessage, createdraft, or updatedraft: Gmail silently rewrites From: to the default address if the value is not a verified alias. Check verification_status is 'accepted'.
list_threads
Search or list conversation threads with Gmail query syntax and pagination. Each result includes subject, latest sender/date, snippet, aggregated labels, and message count inline, so most triage needs no follow-up call. searchscope.complete with an empty list is a definitive 'no such conversation'; an empty search is retried once across spam and trash. Use getthread for the full messages.
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 every message in a thread to trash by adding the TRASH label. Other labels are left in place. Not a permanent delete: use untrashthread to restore the whole conversation. Use listthreads to find thread IDs.
untrash_thread
Restore an entire conversation from trash by removing the TRASH label from its messages. Their other labels are untouched. Use list_threads with q='in:trash' to find trashed thread IDs. Safe to repeat: a thread already out of trash is unchanged.
validate_credential
Validate Gmail credentials. Verifies credentials during setup.
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}
11Open 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}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 }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}FAQs on using Merge's Gmail MCP server
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"
Can employees use Merge Agent Handler to connect their AI tools to Gmail?
Yes, Agent Handler for Employees lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, and other MCP-compatible AI tools to Gmail without bypassing IT governance.
Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Agent Handler and gets individual credentials tied to their identity.
IT also provisions access by role or group via SCIM. A sales rep, for example, gets Gmail to manage outreach, Salesforce to track deals, and Google Calendar to schedule meetings; while a CS manager gets Gmail to handle account communications, Zendesk to track support tickets, and Salesforce to log account notes.
Every tool call an employee's AI makes to Gmail is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.
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
