Sebastianall1977 Gmail MCP

What sebastianall1977-gmail-mcp does

sebastianall1977-gmail-mcp MCP server exposes Gmail operations through the Model Context Protocol. It connects an MCP client to a user's Gmail account and supports message retrieval, sending, deletion, trash management, label changes, thread operations, and draft workflows.

The available API surface also includes mailbox profile access, attachment retrieval, mailbox watch controls, and history-related Gmail functionality. Agents can create, update, inspect, and delete labels, including label configuration such as visibility and color where supported by Gmail. Settings tools cover auto-forwarding, IMAP, POP, vacation responder, and language preferences.

How it works

Authentication uses Google OAuth 2.0. An organization first creates a Google Cloud project, enables the Gmail API, and creates a desktop OAuth client. The OAuth key file is stored locally, then each user runs the authentication command to approve access and obtain a refresh token.

The server can run locally through npx or from a source build. Local MCP clients start it with either the package command or the generated Node.js entry point. A remote deployment can use Smithery CLI and pass the Google client ID, client secret, and user refresh token during setup. The README also references Smithery SDK boilerplate for developers building their own agent application.

Setup and configuration

For local use, install Node.js 18 or newer. Building from source additionally requires pnpm. Create the OAuth key file at ~/.gmail-mcp/gcp-oauth.keys.json, then run npx @shinzolabs/gmail-mcp auth and complete the browser-based consent flow. By default, user credentials are written to ~/.gmail-mcp/credentials.json.

The main configuration paths can be changed with MCP_CONFIG_DIR, GMAIL_OAUTH_PATH, and GMAIL_CREDENTIALS_PATH. Remote operation requires CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN. AUTH_SERVER_PORT controls the temporary OAuth server, while PORT controls Streamable HTTP transport. Telemetry is enabled by default and can be controlled with TELEMETRY_ENABLED.

Tools and capabilities

sebastianall1977-gmail-mcp MCP server includes tools for:

• Listing and retrieving messages, threads, labels, drafts, and attachments.
• Sending messages and drafts, creating or updating drafts, and deleting drafts.
• Applying or removing labels on individual messages, batches, or threads.
• Moving messages and threads to or from trash, or permanently deleting them.
• Creating, updating, partially updating, listing, and deleting labels.
• Reading and changing auto-forwarding, IMAP, POP, vacation responder, and language settings.
• Getting the current Gmail profile and starting or stopping mailbox watch notifications.

These operations can support workflows such as triaging mail, preparing replies as drafts, applying labels to matching messages, and changing account settings through an agent.

Limitations and notes

The server requires access to a Google Cloud OAuth client and user authorization; it is not usable without Gmail API credentials. The README specifies desktop-app OAuth setup for the Google client. Remote connections require the refresh token and client credentials to be supplied separately.

Destructive operations are available, including permanent message or thread deletion and label deletion, so client-side confirmation may be appropriate before invoking them. The provided material does not specify provider support beyond Gmail, nor does it document a separate permission model for individual tools.