Skip to main content
Glama

A Model Context Protocol (MCP) server implementation for the Gmail API, providing a standardized interface for email management, sending, and retrieval.

Features

  • Complete Gmail API coverage including messages, threads, labels, drafts, and settings

  • Support for sending, drafting, and managing emails

  • Label management with customizable colors and visibility settings

  • Thread operations for conversation management

  • Settings management including vacation responder, IMAP/POP, and language settings

  • History tracking for mailbox changes

  • Secure OAuth2 authentication using Google Cloud credentials

Related MCP server: Gmail MCP

Prerequisites

Dependencies

For simplest installation, install Node.js 18+. If you would like to build locally, you will also need to install pnpm.

Google Workspace Setup

To run this MCP server, you will need to set up a Google API Client for your organization, with each user running a script to retrieve their own OAuth refresh token.

Google API Client Setup (once per organization)

  1. Go to the Google Cloud Console.

  2. Create a new project or select an existing one.

  3. Enable the Gmail API for your project.

  4. Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.

  5. Download and save the OAuth keys JSON as ~/.gmail-mcp/gcp-oauth.keys.json. ⚠️ NOTE: to create ~/.gmail-mcp/ through MacOS's Finder app you need to enable hidden files first.

  6. (Optional) For remote server installation (ex. using Smithery CLI), note the CLIENT_ID and CLIENT_SECRET from this file.

Client OAuth (once per user)

  1. Have the user copy ~/.gmail-mcp/gcp-oauth.keys.json to their computer at the same path.

  2. Run npx @shinzolabs/gmail-mcp auth.

  3. A browser window will open where the user may select a profile, review the requested scopes, and approve.

  4. (Optional) For remote server installation, note the file path mentioned in the success message (~/.gmail-mcp/credentials.json by default). The user's REFRESH_TOKEN will be found here.

Client Configuration

There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a Smithery API Key. For local installation, use npx or build from source. Each of these options is explained below.

To add a remote server to your MCP client config.json, run the following command from Smithery CLI:

npx -y @smithery/cli install @shinzo-labs/gmail-mcp

Enter your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN when prompted.

Smithery SDK

If you are developing your own agent application, you can use the boilerplate code here.

NPX Local Install

To install the server locally with npx, add the following to your MCP client config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@shinzolabs/gmail-mcp"
      ]
    }
  }
}

Build from Source

  1. Download the repo:

git clone https://github.com/shinzo-labs/gmail-mcp.git
  1. Install packages and build with pnpm (inside cloned repo):

pnpm i && pnpm build
  1. Add the following to your MCP client config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/path/to/gmail-mcp/dist/index.js"
      ]
    }
  }
}

Config Variables

Variable

Description

Required?

Default

AUTH_SERVER_PORT

Port for the temporary OAuth authentication server

No

3000

CLIENT_ID

Google API client ID (found in GMAIL_OAUTH_PATH)

Yes if remote server connection

''

CLIENT_SECRET

Google API client secret (found in GMAIL_OAUTH_PATH)

Yes if remote server connection

''

GMAIL_CREDENTIALS_PATH

Path to the user credentials file

No

MCP_CONFIG_DIR/credentials.json

GMAIL_OAUTH_PATH

Path to the Google API Client file

No

MCP_CONFIG_DIR/gcp-oauth.keys.json

MCP_CONFIG_DIR

Directory for storing configuration files

No

~/.gmail-mcp

REFRESH_TOKEN

OAuth refresh token (found in GMAIL_CREDENTIALS_PATH)

Yes if remote server connection

''

PORT

Port for Streamable HTTP transport method

No

3000

TELEMETRY_ENABLED

Enable telemetry

No

true

Supported Endpoints

User Management

  • get_profile: Get the current user's Gmail profile

  • stop_mail_watch: Stop receiving push notifications

  • watch_mailbox: Set up push notifications for mailbox changes

Message Management

Managing Messages

  • list_messages: List messages with optional filtering

  • get_message: Get a specific message

  • get_attachment: Get a message attachment

  • modify_message: Modify message labels

  • send_message: Send an email message to specified recipients

  • delete_message: Permanently delete a message

  • trash_message: Move message to trash

  • untrash_message: Remove message from trash

  • batch_modify_messages: Modify multiple messages

  • batch_delete_messages: Delete multiple messages

Label Management

  • list_labels: List all labels

  • get_label: Get a specific label

  • create_label: Create a new label

  • update_label: Update a label

  • patch_label: Partial update of a label

  • delete_label: Delete a label

Thread Management

  • list_threads: List email threads

  • get_thread: Get a specific thread

  • modify_thread: Modify thread labels

  • trash_thread: Move thread to trash

  • untrash_thread: Remove thread from trash

  • delete_thread: Delete a thread

Draft Management

  • list_drafts: List drafts in the user's mailbox

  • get_draft: Get a specific draft by ID

  • create_draft: Create a draft email in Gmail

  • update_draft: Replace a draft's content

  • delete_draft: Delete a draft

  • send_draft: Send an existing draft

Settings Management

Auto-Forwarding

  • get_auto_forwarding: Get auto-forwarding settings

  • update_auto_forwarding: Update auto-forwarding settings

IMAP Settings

  • get_imap: Get IMAP settings

  • update_imap: Update IMAP settings

POP Settings

  • get_pop: Get POP settings

  • update_pop: Update POP settings

Vacation Responder

  • get_vacation: Get vacation responder settings

  • update_vacation: Update vacation responder

Language Settings

  • get_language: Get language settings

  • update_language: Update language settings

Delegates

  • list_delegates: List account delegates

  • get_delegate: Get a specific delegate

  • add_delegate: Add a delegate

  • remove_delegate: Remove a delegate

Filters

  • list_filters: List email filters

  • get_filter: Get a specific filter

  • create_filter: Create a new filter

  • delete_filter: Delete a filter

Forwarding Addresses

  • list_forwarding_addresses: List forwarding addresses

  • get_forwarding_address: Get a specific forwarding address

  • create_forwarding_address: Create a forwarding address

  • delete_forwarding_address: Delete a forwarding address

Send-As Settings

  • list_send_as: List send-as aliases

  • get_send_as: Get a specific send-as alias

  • create_send_as: Create a send-as alias

  • update_send_as: Update a send-as alias

  • patch_send_as: Partial update of a send-as alias

  • verify_send_as: Send verification email

  • delete_send_as: Delete a send-as alias

S/MIME Settings

  • list_smime_info: List S/MIME configurations

  • get_smime_info: Get a specific S/MIME config

  • insert_smime_info: Upload a new S/MIME config

  • set_default_smime_info: Set default S/MIME config

  • delete_smime_info: Delete an S/MIME config

Contributing

Contributions are welcomed and encouraged! Please read CONTRIBUTING.md for guidelines on issues, contributions, and contact information.

Data Collection and Privacy

Shinzo Labs collects limited anonymous telemetry from this server to help improve our products and services. No personally identifiable information is collected as part of this process. Please review the Privacy Policy for more details on the types of data collected and how to opt-out of this telemetry.

License

MIT

Available Tools

64 tools
add_delegateC

Adds a delegate to the specified account

Inputs: delegateEmail (required).

batch_delete_messagesB

Delete multiple messages

Inputs: ids (required).

batch_modify_messagesB

Modify the labels on multiple messages

Inputs: ids (required), addLabelIds, removeLabelIds.

create_draftB

Create a draft email in Gmail. Note the mechanics of the raw parameter.

Inputs: raw, threadId, to, cc, +4 more.

create_filterD

Creates a filter

Inputs: criteria (required), action (required).

create_forwarding_addressB

Creates a forwarding address

Inputs: forwardingEmail (required).

create_labelC

Create a new label

Inputs: name (required), messageListVisibility, labelListVisibility, color.

create_send_asB

Creates a custom send-as alias

Inputs: sendAsEmail (required), displayName, replyToAddress, signature, +2 more.

delete_draftC

Delete a draft

Inputs: id (required).

delete_filterB

Deletes a filter

Inputs: id (required).

delete_forwarding_addressB

Deletes the specified forwarding address

Inputs: forwardingEmail (required).

delete_labelC

Delete a label

Inputs: id (required).

delete_messageA

Immediately and permanently delete a message

Inputs: id (required).

delete_send_asB

Deletes the specified send-as alias

Inputs: sendAsEmail (required).

delete_smime_infoB

Deletes the specified S/MIME config for the specified send-as alias

Inputs: sendAsEmail (required), id (required).

delete_threadB

Delete a thread

Inputs: id (required).

get_attachmentC

Get a message attachment

Inputs: messageId (required), id (required).

get_auto_forwardingA

Gets auto-forwarding settings

Inputs: no named parameters.

get_delegateA

Gets the specified delegate

Inputs: delegateEmail (required).

get_draftC

Get a specific draft by ID

Inputs: id (required), includeBodyHtml.

get_filterC

Gets a filter

Inputs: id (required).

get_forwarding_addressC

Gets the specified forwarding address

Inputs: forwardingEmail (required).

get_imapB

Gets IMAP settings

Inputs: no named parameters.

get_labelA

Get a specific label by ID

Inputs: id (required).

get_languageB

Gets language settings

Inputs: no named parameters.

get_messageA

Get a specific message by ID with format options

Inputs: id (required), includeBodyHtml.

get_popB

Gets POP settings

Inputs: no named parameters.

get_profileA

Get the current user's Gmail profile

Inputs: no named parameters.

get_send_asA

Gets the specified send-as alias

Inputs: sendAsEmail (required).

get_smime_infoB

Gets the specified S/MIME config for the specified send-as alias

Inputs: sendAsEmail (required), id (required).

get_threadB

Get a specific thread by ID

Inputs: id (required), includeBodyHtml.

get_vacationB

Get vacation responder settings

Inputs: no named parameters.

insert_smime_infoB

Insert (upload) the given S/MIME config for the specified send-as alias

Inputs: sendAsEmail (required), encryptedKeyPassword (required), pkcs12 (required).

list_delegatesA

Lists the delegates for the specified account

Inputs: no named parameters.

list_draftsC

List drafts in the user's mailbox

Inputs: maxResults, q, includeSpamTrash, includeBodyHtml.

list_filtersA

Lists the message filters of a Gmail user

Inputs: no named parameters.

list_forwarding_addressesB

Lists the forwarding addresses for the specified account

Inputs: no named parameters.

list_labelsB

List all labels in the user's mailbox

Inputs: no named parameters.

list_messagesC

List messages in the user's mailbox with optional filtering

Inputs: maxResults, pageToken, q, labelIds, +2 more.

list_send_asB

Lists the send-as aliases for the specified account

Inputs: no named parameters.

list_smime_infoB

Lists S/MIME configs for the specified send-as alias

Inputs: sendAsEmail (required).

list_threadsB

List threads in the user's mailbox

Inputs: maxResults, pageToken, q, labelIds, +2 more.

modify_messageB

Modify the labels on a message

Inputs: id (required), addLabelIds, removeLabelIds.

modify_threadB

Modify the labels applied to a thread

Inputs: id (required), addLabelIds, removeLabelIds.

patch_labelB

Patch an existing label (partial update)

Inputs: id (required), name, messageListVisibility, labelListVisibility, +1 more.

patch_send_asC

Patches the specified send-as alias

Inputs: sendAsEmail (required), displayName, replyToAddress, signature, +2 more.

remove_delegateC

Removes the specified delegate

Inputs: delegateEmail (required).

send_draftC

Send an existing draft

Inputs: id (required).

send_messageC

Send an email message to specified recipients. Note the mechanics of the raw parameter.

Inputs: raw, threadId, to, cc, +4 more.

set_default_smime_infoC

Sets the default S/MIME config for the specified send-as alias

Inputs: sendAsEmail (required), id (required).

stop_mail_watchB

Stop receiving push notifications for the given user mailbox

Inputs: no named parameters.

trash_messageA

Move a message to the trash

Inputs: id (required).

trash_threadB

Move a thread to the trash

Inputs: id (required).

untrash_messageB

Remove a message from the trash

Inputs: id (required).

untrash_threadA

Remove a thread from the trash

Inputs: id (required).

update_auto_forwardingC

Updates automatic forwarding settings

Inputs: enabled (required), emailAddress (required), disposition (required).

update_imapC

Updates IMAP settings

Inputs: enabled (required), expungeBehavior, maxFolderSize.

update_labelC

Update an existing label

Inputs: id (required), name, messageListVisibility, labelListVisibility, +1 more.

update_languageC

Updates language settings

Inputs: displayLanguage (required).

update_popC

Updates POP settings

Inputs: accessWindow (required), disposition (required).

update_send_asC

Updates a send-as alias

Inputs: sendAsEmail (required), displayName, replyToAddress, signature, +2 more.

update_vacationC

Update vacation responder settings

Inputs: enableAutoReply (required), responseBodyPlainText (required), responseSubject, restrictToContacts, +3 more.

verify_send_asB

Sends a verification email to the specified send-as alias

Inputs: sendAsEmail (required).

watch_mailboxC

Watch for changes to the user's mailbox

Inputs: topicName (required), labelIds, labelFilterAction.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 64 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific Gmail resources like messages, drafts, labels, filters, delegates, and settings. However, some overlap exists between batch_modify_messages and modify_message, and between trash/untrash operations for messages and threads, which could cause minor confusion. Overall, descriptions are clear enough to differentiate them in most cases.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as create_draft, delete_label, get_attachment, update_vacation, and list_threads. All tools use snake_case without deviation, making them predictable and easy to parse for an agent.

    Tool Count2/5

    With 64 tools, this server is excessively large for a typical MCP scope, likely overwhelming for agents and increasing complexity. While Gmail is a broad domain, many tools could be consolidated (e.g., separate trash/untrash for messages and threads) or omitted for a more focused interface. This count feels heavy and unwieldy.

    Completeness5/5

    The tool set provides comprehensive coverage of Gmail's functionality, including CRUD operations for messages, drafts, labels, filters, delegates, and send-as aliases, plus settings management for forwarding, IMAP/POP, language, vacation responders, and S/MIME. There are no obvious gaps; agents can handle full email workflows from creation to deletion.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers