Overview

The Google Gmail MCP connector enables your Leena AI Agents to integrate with your organization's Gmail platform, facilitating automated email workflows such as searching and reading emails, drafting messages, and managing labels.

The Gmail MCP server is Google's official remote Model Context Protocol (MCP) server that securely exposes a user's Gmail mailbox as tools for AI agents. Leena AI connects to it through the MCP connector, allowing Agents to search email threads, read messages and conversations, create drafts (including replies), and organize the mailbox with labels — all while respecting each user's existing Gmail access and permissions.

API Details

Leena AI integrates with the Gmail MCP server via the Model Context Protocol (MCP) over Streamable HTTP.

MCP server URL: https://gmailmcp.googleapis.com/mcp/v1

Documentation link: https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server

Setup

The Gmail MCP server is connected through Leena AI's MCP connector. The connector supports the following authentication types: No authentication, Custom auth (static headers), Admin OAuth 2.0, and User OAuth 2.0.

The Gmail MCP server uses OAuth 2.0 with an OAuth client created in your Google Cloud project. For Gmail MCP, use one of the following:

• User OAuth 2.0 (recommended): Each employee signs in with their own Google account, and every action runs on the signed-in user's own mailbox with their existing Gmail permissions.
• Admin OAuth 2.0: A single admin/shared account completes the OAuth flow once, and all actions run on that account's mailbox.

Prerequisites

Before setting up the Google Gmail MCP connector, ensure you have:

• Administrator access to your Google Cloud Console and a Google Cloud project
• Ability to enable APIs and create OAuth applications in the Google Cloud project
• Enrollment in the Google Workspace Developer Preview Program (the Gmail MCP server is in Developer Preview)
• Google Workspace / Gmail accounts for the employees who will use the actions
• Access to your Leena AI workspace with connector management permissions

Get credentials

Here is how to prepare the Google Cloud project and create an OAuth client:

1. Log in to Google Cloud Console (Ensure you're signed in as an admin) and select or create a project.
2. Enable the Gmail API:
   1. Go to API & Services > Library
   2. Search for "Gmail API" (gmail.googleapis.com)
   3. Click Enable
3. Enable the Gmail MCP API:
   1. Go to API & Services > Library
   2. Search for "Gmail MCP API" (gmailmcp.googleapis.com)
   3. Click Enable
4. Configure the OAuth consent screen:
   1. Navigate to Google Auth Platform > Branding (OAuth consent screen)
   2. Enter the app name and support email
   3. Under Audience, choose Internal so the app is limited to users in your Google Workspace organization
5. Create OAuth Client:
   1. Navigate to API & Services > Credentials
   2. Click + CREATE CREDENTIALS
   3. Select OAuth client ID
6. Configure OAuth Client Details
   1. Application Type: Web application
   2. Name: Enter a descriptive name for your application
   3. Authorized redirect URIs: This will be filled later from Leena AI
7. Save and Note Credentials (The client secret is displayed only once during creation)

The Gmail MCP server uses the following OAuth scopes:

• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/gmail.compose

Add connection

Here is how to add a connection on Leena AI:

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations
3. Search for "Custom MCP" and select it from the list to add its new connector
4. Give the connection a name (for example, "Google Gmail MCP")
5. Start configuring the connector
   1. MCP remote URL: The Gmail MCP server URL — https://gmailmcp.googleapis.com/mcp/v1
   2. Authentication type: Select "User OAuth 2.0" (recommended) or "Admin OAuth 2.0"
6. Fill in the OAuth fields:
   1. Redirect URI: The callback URL for the OAuth flow (auto-generated by Leena AI)
   2. Client ID: OAuth client ID from your Google Cloud project
   3. Client secret: OAuth client secret from your Google Cloud project
7. Copy the Redirect URI and update the Google Cloud OAuth client
   1. Copy the auto-generated Redirect URI from Leena AI
   2. Go back to Google Cloud Console > API & Services > Credentials
   3. Edit your OAuth client and add the Redirect URI to Authorized redirect URIs
   4. Save the changes
8. Complete the OAuth flow and save the configuration
   1. Click Connect in Leena AI for the Google Gmail MCP connection
   2. You'll be redirected to Google's authorization page
   3. Sign in to your Google account if prompted
   4. Click Allow to grant access to Gmail
   5. You'll be redirected back to Leena AI with a successful connection
   6. The connector will be saved
9. Once the connection is authorized, the available actions are fetched automatically from the Gmail MCP server and can be selected while building skills (workflows)

Actions

Actions for this connector are discovered dynamically from the Gmail MCP server. Every action runs on the authenticated user's own mailbox. The server supports searching and reading emails, managing drafts, and managing labels; sending is done by creating a draft that the user reviews and sends from Gmail.

The following actions are supported for the Google Gmail MCP connector:

search_threads

Lists email threads from the authenticated user's Gmail account. The action can filter threads using a Gmail search query and supports pagination. This action can be leveraged by the Leena AI Orchestrator/Agent to locate conversations before reading or labelling them. Here are some common use cases:

• Inbox Triage: List unread threads from the last few days
• Sender Search: Find conversations from a specific person or mailing list
• Attachment Search: Find threads that contain attachments
• Follow-up Discovery: Find starred or important threads that need action

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters.

Optional

Here is a sample JSON input:

//Search Unread Threads from a Sender

{
  "query": "from:[email protected] is:unread newer_than:7d",
  "pageSize": 20
}

//Fetch the Next Page

{
  "query": "has:attachment",
  "pageSize": 20,
  "pageToken": "ChDJk9..."
}

Response

The action returns a list of matching threads, each containing:

• Thread ID
• Snippet and subject (in the default view)
• From, To, CC, and BCC addresses
• Date and label IDs
• Page token for the next page (when more results are available)

get_thread

Retrieves a specific email thread from the authenticated user's Gmail account, including the list of its messages. The Agent can leverage the skill (workflow), which has been designed to read a full conversation, once the user specifies the thread. Here are some common use cases:

• Conversation Review: Read the full back-and-forth of an email conversation
• Summarization: Summarize a long thread for the user
• Context for Replies: Read a thread before drafting a reply

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "threadId": "18c1a2b3d4e5f6a7",
  "messageFormat": "FULL_CONTENT"
}

Response

The action returns the thread with its messages, each containing (in the default format):

• Message ID and label IDs
• Snippet and subject
• Sender, To, CC, and BCC recipients
• Date
• Plain-text body and HTML body
• Attachment IDs and attachment details

get_message

Retrieves a specific email message from the authenticated user's Gmail account by its unique message ID. Use this action to inspect a single, individual email when the message ID is already known (for example, from a previous search); use get_thread to read an entire conversation. Here are some common use cases:

• Detailed Read: Get the full content of a specific message
• Exact Wording: Check the exact text of an email
• Attachment Metadata: Examine attachment names for a single email

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "messageId": "18c1a2b3d4e5f6a7"
}

Response

The action returns the message details including:

• Message ID and thread ID
• Subject and snippet
• Sender and recipients
• Date and label IDs
• Body content and attachment metadata (in the default format)

create_draft

Creates a new draft email in the authenticated user's Gmail account. The Agent can leverage the skill (workflow), which has been designed to compose a draft — either a new email or a reply to an existing message — once the user raises a query to do so. The draft stays in the user's Drafts folder for review and sending from Gmail. Here are some common use cases:

• Assisted Replies: Draft a reply to an email so the user can review and send it
• Composed Emails: Turn a conversational request into a ready-to-send draft
• Templated Communication: Prepare drafts for approvals, follow-ups, or announcements

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters (provide the recipients, subject, and body relevant to your use case).

Optional

Here is a sample JSON input:

//Create a New Draft

{
  "to": ["[email protected]"],
  "cc": ["[email protected]"],
  "subject": "Offer Letter - Next Steps",
  "body": "Hi John,\n\nPlease find the next steps for your offer below.\n\nRegards,\nHR Team"
}

//Create a Reply Draft

{
  "to": ["[email protected]"],
  "body": "Thanks Jane, the updated policy has been noted.",
  "replyToMessageId": "18c1a2b3d4e5f6a7"
}

Response

Upon successful creation, the action returns:

• The unique ID of the draft message

list_drafts

Lists draft emails from the authenticated user's Gmail account. The action can filter drafts based on a query string and supports pagination. Here are some common use cases:

• Draft Review: List the user's pending drafts
• Draft Lookup: Find a draft by subject or recipient before updating or sending it from Gmail
• Cleanup: Identify old drafts that are no longer needed

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters.

Optional

Here is a sample JSON input:

{
  "query": "subject:offer",
  "pageSize": 10
}

Response

The action returns a list of drafts, each containing (in the default view):

• Draft ID and thread ID
• To, CC, and BCC recipients
• Date
• Subject and body
• Page token for the next page (when more results are available)

list_labels

Lists all labels available in the authenticated user's Gmail account. Use this action to discover the ID of a label before calling the label_thread, unlabel_thread, label_message, or unlabel_message actions. Here are some common use cases:

• Label Discovery: Find the label ID that corresponds to a label's display name
• Mailbox Overview: List the system and user-defined labels in the mailbox
• Pre-labelling Step: Fetch label IDs before organizing messages or threads

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

This action has no mandatory input parameters.

Optional

Here is a sample JSON input:

{
  "pageSize": 50
}

Response

The action returns the list of labels in the mailbox, each containing:

• Label ID (system label IDs such as INBOX, STARRED, UNREAD, IMPORTANT, or user-defined label IDs)
• Label display name

label_message

Adds one or more labels to a specific message in the authenticated user's Gmail account. The Agent can leverage the skill (workflow), which has been designed to organize a single email, once the user specifies the message and labels. Here are some common use cases:

• Prioritization: Star or mark a specific email as important
• Categorization: Apply a user-defined label (e.g., "Expenses") to an email
• Mark as Unread: Add the UNREAD label so the user revisits an email

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Here is a sample JSON input:

{
  "messageId": "18c1a2b3d4e5f6a7",
  "labelIds": ["STARRED", "IMPORTANT"]
}

Response

Upon successful update, the action returns confirmation that the labels were added to the message.

unlabel_message

Removes one or more labels from a specific message in the authenticated user's Gmail account. The Agent can leverage the skill (workflow), which has been designed to update a single email's labels, once the user specifies the message and labels. Here are some common use cases:

• Mark as Read: Remove the UNREAD label from an email
• Unstar: Remove the STARRED label once an email is handled
• Recategorization: Remove a user-defined label from an email

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Here is a sample JSON input:

{
  "messageId": "18c1a2b3d4e5f6a7",
  "labelIds": ["UNREAD"]
}

Response

Upon successful update, the action returns confirmation that the labels were removed from the message.

label_thread

Adds labels to an entire thread in the authenticated user's Gmail account. This operation affects all messages currently in the thread and any future messages added to it. Here are some common use cases:

• Conversation Tagging: Apply a project or ticket label to a whole conversation
• Prioritize Threads: Mark an entire conversation as important
• Inbox Organization: Keep every future message of a thread under the same label

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Here is a sample JSON input:

{
  "threadId": "18c1a2b3d4e5f6a7",
  "labelIds": ["Label_1234567890"]
}

Response

Upon successful update, the action returns confirmation that the labels were added to the thread.

unlabel_thread

Removes labels from an entire thread in the authenticated user's Gmail account. This operation affects all messages currently in the thread. Here are some common use cases:

• Archive Conversations: Remove the INBOX label to archive a thread
• Mark Thread as Read: Remove the UNREAD label from a whole conversation
• Label Cleanup: Remove a project label once the conversation is closed

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Here is a sample JSON input:

{
  "threadId": "18c1a2b3d4e5f6a7",
  "labelIds": ["UNREAD"]
}

Response

Upon successful update, the action returns confirmation that the labels were removed from the thread.