Gmail MCP Server

How to use

You connect to the Gmail MCP server from your MCP client to perform common email tasks. Use the available endpoints to list and read messages, manage threads and labels, compose and send emails, handle drafts, and adjust settings such as forwarding, language, and vacation responders. The server handles authentication via Google Cloud credentials and exposes a set of organized endpoints so your agent can work with Gmail in a uniform way.

How to install

Prerequisites: you need Node.js and a package manager installed on your system. You can run the server locally, or connect to a remote MCP host.

Option A — NPX local install (quick start) This installs the MCP server for use directly from the npm registry.

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

Option B — Build from source (requires cloning the repo, installing dependencies, and building) This is used when you want to run the server from your own build artifacts.

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

# Step 2: Install dependencies and build
pnpm i && pnpm build

# Step 3: Run from the built artifact
# After building, configure your client to start the compiled server

Configuration for running from a built artifact (example) This starts the server using Node with the generated index in dist.

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

Configuration and connections

The Gmail MCP server relies on OAuth credentials stored on your system. You configure an MCP client to connect either via a remote HTTP endpoint (if you have a hosted MCP server) or by running the server locally through NPX or a built artifact.

Additional notes

Key prerequisites include setting up a Google API project, enabling the Gmail API, and obtaining OAuth credentials. The service uses these credentials to securely access Gmail data and perform actions on behalf of users.

Security considerations

Protect your OAuth client IDs, client secrets, and refresh tokens. Do not share credentials publicly. Use secure storage paths and restrict access to credentials to authorized users and processes.

Troubleshooting

If you encounter authentication errors, verify that the OAuth credentials are correctly placed at the expected path and that refresh tokens are valid. Check that the MCP client has the necessary scopes for Gmail operations and that your environment variables (if used) are set correctly. Ensure the Gmail API is enabled for your Google Cloud project.

list_messages

List messages with optional filtering to locate specific emails.

get_message

Retrieve a specific Gmail message by ID.

get_attachment

Fetch an attachment from a message.

modify_message

Modify 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 trash.

untrash_message

Restore a trashed message.

batch_modify_messages

Apply changes to multiple messages in a single operation.

batch_delete_messages

Delete multiple messages in a single operation.

list_labels

List all labels in the user's mailbox.

get_label

Get details about 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

Restore a trashed 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.

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 specific 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.

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.