Gmail MCP

Gmail MCP provides comprehensive integration with the Gmail API, enabling AI coding assistants to manage emails, conversations, and mailbox settings directly through Google Workspace accounts. Key features: - Complete Gmail API coverage including sending, receiving, and drafting emails - Thread and conversation management for organized communication - Label management with customizable colors and visibility settings - Advanced mailbox settings including vacation responders and IMAP/POP configuration - Draft handling and email history tracking for mailbox changes - Secure OAuth2 authentication through Google Cloud credentials

Gmail MCP Server

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

Features

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 MCP client config.json, run the following command from Smithery CLI:

npx -y @smithery/cli install @shinzo-labs/gmail-mcp

Enter your CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN when prompted.

Smithery SDK

If you are developing your own agent application, you can use the boilerplate code here.

NPX Local Install

To install the server locally with npx, add the following to your MCP client config.json:

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

Build from Source

1. Download the repo:

git clone https://github.com/shinzo-labs/gmail-mcp.git

2. Install packages and build with pnpm (inside cloned repo):

pnpm i && pnpm build

3. Add the following to your MCP client config.json:

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

Config Variables

|