Faithk7 Gmail MCP

What faithk7-gmail-mcp MCP server does

faithk7-gmail-mcp MCP server connects an MCP-compatible client to the Gmail API. Its tools cover mailbox inspection and message operations, including listing and retrieving messages, reading attachments, changing labels, sending mail, moving messages to or from trash, and permanently deleting messages. Batch operations are available for modifying or deleting multiple messages.

The server also exposes Gmail threads, labels, drafts, and selected account settings. Agents can create, update, send, and remove drafts; create and edit labels; and manage thread labels or deletion state. Settings tools cover auto-forwarding, IMAP, POP, vacation responder, and language preferences. Mailbox watch tools can start or stop push notifications for changes, while the history capability supports tracking mailbox changes.

How it works

Authentication uses OAuth2 credentials created in Google Cloud. An administrator or developer enables the Gmail API, creates a Desktop OAuth client, and saves the client keys in the server’s configuration directory. Each user then runs the authentication command and approves the requested scopes in a browser. The resulting credentials include a refresh token used for later access.

faithk7-gmail-mcp MCP server can communicate with an MCP client through a local npx process or a Node.js process built from source. The documentation also describes remote installation through the Smithery CLI and a Streamable HTTP transport. Remote connections require the Google client ID, client secret, and user refresh token as configuration values.

Setup and configuration

Node.js 18 or newer is the simplest local prerequisite. Building from source additionally requires pnpm. For local OAuth setup, place the Google client file at ~/.gmail-mcp/gcp-oauth.keys.json, then run:

npx @shinzolabs/gmail-mcp auth

A local MCP client can launch the package with npx @shinzolabs/gmail-mcp. Alternatively, clone the project, install dependencies, build it with pnpm, and point the client at dist/index.js.

The default configuration directory is ~/.gmail-mcp. MCP_CONFIG_DIR, GMAIL_OAUTH_PATH, and GMAIL_CREDENTIALS_PATH can change where OAuth and user credential files are stored. AUTH_SERVER_PORT controls the temporary authentication server, while PORT controls Streamable HTTP. Telemetry is enabled by default and can be changed with TELEMETRY_ENABLED.

Tools and capabilities

Available tool groups include:

• Messages: list, retrieve, send, modify, trash, restore, delete, and batch-process messages; retrieve attachments.
• Threads: list, retrieve, relabel, trash, restore, and delete threads.
• Labels: list, retrieve, create, update, partially update, and delete labels.
• Drafts: list, retrieve, create, replace, delete, and send drafts.
• Settings: read and update forwarding, IMAP, POP, vacation responder, and language settings.
• User and mailbox state: retrieve the profile, configure or stop mailbox watches, and access history-related mailbox changes.

Limitations and notes

Gmail API access must be enabled in a Google Cloud project, and users must approve OAuth access before the server can operate on their mail. Remote deployment needs credentials supplied separately from the local file-based flow. The material does not identify client-specific features or permissions beyond support for MCP client configuration, local execution, Smithery installation, and Streamable HTTP transport.