A Model Context Protocol (MCP) server implementation for the Gmail API, providing a standardized interface for email management, sending, and retrieval.

Features

• Complete Gmail API coverage including messages, threads, labels, drafts, and settings
• Support for sending, drafting, and managing emails
• Label management with customizable colors and visibility settings
• Thread operations for conversation management
• Settings management including vacation responder, IMAP/POP, and language settings
• History tracking for mailbox changes
• Secure OAuth2 authentication using Google Cloud credentials

Prerequisites

Dependencies

For simplest installation, install Node.js 18+. If you would like to build locally, you will also need to install pnpm.

Google Workspace Setup

To run this MCP server, you will need to set up a Google API Client for your organization, with each user running a script to retrieve their own OAuth refresh token.

Google API Client Setup (once per organization)

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Enable the Gmail API for your project.
4. Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.
5. Download and save the OAuth keys JSON as ~/.gmail-mcp/gcp-oauth.keys.json. ⚠️ NOTE: to create ~/.gmail-mcp/ through MacOS's Finder app you need to enable hidden files first.
6. (Optional) For remote server installation (ex. using Smithery CLI), note the CLIENT_ID and CLIENT_SECRET from this file.

Client OAuth (once per user)

1. Have the user copy ~/.gmail-mcp/gcp-oauth.keys.json to their computer at the same path.
2. Run npx @shinzolabs/gmail-mcp auth.
3. A browser window will open where the user may select a profile, review the requested scopes, and approve.
4. (Optional) For remote server installation, note the file path mentioned in the success message (~/.gmail-mcp/credentials.json by default). The user's REFRESH_TOKEN will be found here.

Client Configuration

There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a Smithery API Key. For local installation, use npx or build from source. Each of these options is explained below.

Smithery Remote Server (Recommended)

To add a remote server to your M

... View full README on GitHub