MCP 服务器

Gmail MCP

Enables comprehensive Gmail management through the Gmail API, including sending/receiving emails, organizing labels and threads, managing drafts, and configuring account settings with secure OAuth2 authentication.

README

Gmail MCP

A Model Context Protocol (MCP) 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

To run this MCP server, you first 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)

Go to the Google Cloud Console.
Create a new project or select an existing one.
Enable the Gmail API for your project.
Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.
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.
(Optional) For remote server installation (ex. using Smithery CLI), note the CLIENT_ID and CLIENT_SECRET from this file.

Client OAuth (once per user)

Have the user copy ~/.gmail-mcp/gcp-oauth.keys.json to their computer at the same path.
Run npx @shinzolabs/gmail-mcp auth.
A browser window will open where the user may select a profile, review the requested scopes, and approve.
(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

Download the repo:

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

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

pnpm i && pnpm build

Add the following to your MCP client config.json:

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

Config Variables

Variable	Description	Required?	Default
`AUTH_SERVER_PORT`	Port for the temporary OAuth authentication server	No	`3000`
`CLIENT_ID`	Google API client ID (found in `GMAIL_OAUTH_PATH`)	Yes if remote server connection	`''`
`CLIENT_SECRET`	Google API client secret (found in `GMAIL_OAUTH_PATH`)	Yes if remote server connection	`''`
`GMAIL_CREDENTIALS_PATH`	Path to the user credentials file	No	`MCP_CONFIG_DIR/credentials.json`
`GMAIL_OAUTH_PATH`	Path to the Google API Client file	No	`MCP_CONFIG_DIR/gcp-oauth.keys.json`
`MCP_CONFIG_DIR`	Directory for storing configuration files	No	`~/.gmail-mcp`
`REFRESH_TOKEN`	OAuth refresh token (found in `GMAIL_CREDENTIALS_PATH`)	Yes if remote server connection	`''`
`PORT`	Port for Streamable HTTP transport method	No	`3000`