Skip to main content
The gmail MCP adapter wraps the Gmail REST API v1. Use it in workflow mcp_call steps to send notifications, search inboxes, and reply to threads.

​
Prerequisites

  • A Google account with Gmail enabled
  • project_contributor access in your workspace
  • Gmail API enabled in your Google Cloud project (handled automatically when connecting through the Console)

​
Connect in AgentRuntime

1

Connect Google

On Connections, use the Google account card and complete OAuth. Enable the Gmail service for your account. See Google Workspace setup and Connections.
2

Add gmail MCP instance

Go to MCP, click Add instance for gmail. Open Instance config, wire your Google connection, and set the profile active.
3

Add a workflow step

In Workflow Studio, add an mcp_call step targeting your gmail instance. Pick a tool and configure tool_args.

​
What you can build

  • Run notifications — On workflow success or failure, send_email to operators with run ID and a Command Center link.
  • Inbox triage — search_emails for is:unread label:support → LLM draft → human_task → reply_to_email.
  • Lead alert — Webhook from a form → send_email to sales with submission details and CRM link.
  • Digest reports — Postgres or Sheets data → LLM summary → send_email on a schedule.

​
Tools

ToolDescription
send_emailSend an email through the connected Gmail account
get_emailRetrieve a message by ID (from, to, subject, date, snippet)
search_emailsSearch with Gmail query syntax (e.g. from:user@example.com is:unread)
reply_to_emailReply to an existing message; supports reply-all

​
Example

Send a notification after a workflow completes: 
{
  "id": "notify-team",
  "type": "mcp_call",
  "name": "Send summary email",
  "tool_name": "send_email",
  "tool_args": {
    "to": "team@example.com",
    "subject": "Workflow complete: {{input.workflow_name}}",
    "body": "Run {{input.run_id}} finished successfully."
  },
  "depends_on": ["generate-summary"],
  "timeout_s": 30
}

​
Configuration

The instance inherits OAuth tokens from your Google connection. Optional config profile fields:
KeyRequiredDefaultDescription
user_idNomeGmail user ID (me = authenticated account)
sender_emailNo—Default From address

​
Gmail search syntax

search_emails accepts standard Gmail operators:
  • from:sender@example.com
  • is:unread
  • subject:invoice
  • after:2026/01/01
Combine operators: from:alerts@example.com is:unread newer_than:7d

​
Troubleshooting

IssueFix
Reconnect prompt on connectionRe-authorize Google OAuth; Gmail scopes may have been revoked
403 from Gmail APIConfirm Gmail API is enabled and the account has send/read permissions
Empty search resultsVerify query syntax; test the same query in Gmail’s web UI