Gmail

This Gmail MCP Server provides a standard, pluggable interface to manage Gmail data and actions through the Model Context Protocol. You can manage messages, threads, labels, drafts, settings, and more, with secure OAuth2 authentication and scalable deployment options for remote or local use.

How to use

You connect a compatible MCP client to this server to perform Gmail operations. Use the client to list and retrieve messages, compose and send mail, manage labels and threads, handle drafts, and adjust account settings. The server exposes a wide range of endpoints for mailbox management, including watching for mailbox changes, handling auto-forwarding, IMAP/POP settings, vacation responders, and language configuration. All actions authenticate via OAuth2 using Google Cloud credentials, keeping access secure as you scale usage across users.

How to install

Prerequisites: install Node.js 18 or newer. If you plan to build locally, also install pnpm.

# Remote (Smithery) server approach
npx -y @smithery/cli install @shinzo-labs/gmail-mcp

# When prompted, provide CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN

Local installation from source using npm/npx should follow this flow. You clone the project, install dependencies, build, and then run the server locally with the built artifact.

# Step 1: clone the repository
git clone https://github.com/shinzo-labs/gmail-mcp.git

# Step 2: install dependencies and build (uses pnpm)
pnpm i && pnpm build

# Step 3: run the built server locally
# The server is started via node against the built index.js in dist
node /path/to/gmail-mcp/dist/index.js

Additional setup notes

If you prefer a remote server setup, you can use the Smithery CLI to install the Gmail MCP Server and provide OAuth credentials at runtime.

Config and environment

Configure the client with the runtime command that starts the MCP server. For a local build, the recommended start path is the built index at dist/index.js.

Available tools

get_profile

Retrieve the current Gmail profile for the authenticated user.

stop_mail_watch

Stop receiving push notifications for mailbox changes.

watch_mailbox

Set up push notifications to monitor mailbox changes.

list_messages

List messages with optional filtering and pagination.

get_message

Retrieve a specific message by ID.

get_attachment

Download an email attachment by ID.

modify_message

Change labels or other metadata on a message.

send_message

Send an email to specified recipients.

delete_message

Permanently delete a message.

trash_message

Move a message to the trash.

untrash_message

Restore a message from the trash.

batch_modify_messages

Modify labels on multiple messages in a batch.

batch_delete_messages

Delete multiple messages in a batch.

list_labels

List all labels for the user.

get_label

Retrieve a specific label.

create_label

Create a new label.

update_label

Update an existing label.

patch_label

Partially update a label.

delete_label

Delete a label.

list_threads

List email threads.

get_thread

Get a specific thread.

modify_thread

Modify thread labels.

trash_thread

Move a thread to trash.

untrash_thread

Untrash a thread.

delete_thread

Delete a thread.

list_drafts

List drafts in the mailbox.

get_draft

Get a draft by ID.

create_draft

Create a new draft email.

update_draft

Replace a draft's content.

delete_draft

Delete a draft.

send_draft

Send an existing draft.

get_auto_forwarding

Get auto-forwarding settings.

update_auto_forwarding

Update auto-forwarding settings.

get_imap

Get IMAP settings.

update_imap

Update IMAP settings.

get_pop

Get POP settings.

update_pop

Update POP settings.

get_vacation

Get vacation responder settings.

update_vacation

Update vacation responder.

get_language

Get language settings.

update_language

Update language settings.

list_delegates

List account delegates.

get_delegate

Get a specific delegate.

add_delegate

Add a delegate.

remove_delegate

Remove a delegate.

list_filters

List email filters.

get_filter

Get a specific filter.

create_filter

Create a new filter.

delete_filter

Delete a filter.

list_forwarding_addresses

List forwarding addresses.

get_forwarding_address

Get a forwarding address.

create_forwarding_address

Create a forwarding address.

delete_forwarding_address

Delete a forwarding address.

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 for a send-as alias.

delete_send_as

Delete a send-as alias.

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.