Gmail

What is Gmail?

A Model Context Protocol (MCP) server implementation for the Gmail API, providing a standardized interface for email management, sending, and retrieval. It enables AI agents and MCP-compatible clients to interact with Gmail programmatically through a unified set of tools.

How to use Gmail?

After setting up a Google Cloud project and enabling the Gmail API, users run npx @shinzolabs/gmail-mcp auth to obtain an OAuth refresh token. The server can then be installed locally via npx or by building from source, or used as a remote server through Smithery CLI. Configuration variables such as CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN are set in the MCP client's config file.

Key features of Gmail

• Complete coverage of the Gmail API (messages, threads, labels, drafts, settings)
• Send, draft, and manage emails with full message manipulation
• Label management with customizable colors and visibility
• Thread operations for conversation-based management
• Settings management (vacation responder, IMAP/POP, language, filters)
• History tracking for mailbox changes
• Secure OAuth2 authentication using Google Cloud credentials

Use cases of Gmail

• Automate email sending and drafting from within an AI assistant
• Manage labels and threads to organize a Gmail inbox programmatically
• Configure vacation responders or IMAP/POP settings without manual clicks
• Integrate with building an AI-powered email client or chatbot

FAQ from Gmail

What are the prerequisites for using this server?

You need Node.js 18+, a Google Cloud project with the Gmail API enabled, and an OAuth 2.0 Client ID (Desktop app type). Each user must run the auth command to generate a refresh token.

How do I obtain a Gmail OAuth refresh token?

After setting up the Google API client once per organization, each user copies the OAuth keys file to ~/.gmail-mcp/gcp-oauth.keys.json and runs npx @shinzolabs/gmail-mcp auth. A browser window opens to approve scopes, and the refresh token is saved.

Is telemetry collected, and can I opt out?

Yes, limited anonymous telemetry is collected by default to improve the product. No personally identifiable information is included. You can disable telemetry by setting the environment variable TELEMETRY_ENABLED=false.

Where are credentials and configuration files stored?

By default, the Google API client keys are stored at ~/.gmail-mcp/gcp-oauth.keys.json and user credentials at ~/.gmail-mcp/credentials.json. You can override these paths using GMAIL_OAUTH_PATH and GMAIL_CREDENTIALS_PATH.

Can I run this server remotely (e.g., on Smithery)?

Yes. Use the Smithery CLI (npx -y @smithery/cli install @shinzo-labs/gmail-mcp) and provide your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN when prompted. The server will be hosted remotely and accessible to your MCP client.