Gmail API Integration Server provides comprehensive access to Gmail's email management capabilities through the Model Context Protocol. It enables AI assistants to interact with Gmail accounts for sending, organizing, and managing emails programmatically. Key features: - Send emails and create drafts directly from Gmail accounts - Retrieve, search, and manage messages and conversation threads - Organize emails with label management including custom colors and visibility settings - Configure mailbox settings including vacation responders, IMAP/POP access, and language preferences - Track mailbox history and monitor changes - Secure OAuth2 authentication through Google Cloud credentials

Gmail MCP

[](https://badge.fury.io/js/@shinzolabs%2Fgmail-mcp) [](https://smithery.ai/server/@shinzo-labs/gmail-mcp)

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

Features

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)

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

| 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 | | `GM