home / mcp / gmail mcp server

Gmail MCP Server

Provides Gmail access via MCP to list, read, send, search, and manage Gmail emails.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "brentwpeterson-mcp-gmail": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-gmail/dist/index.js"
      ],
      "env": {
        "GMAIL_CONFIG_DIR": "~/.mcp-gmail",
        "GMAIL_CREDENTIALS_PATH": "~/.mcp-gmail/credentials.json"
      }
    }
  }
}

This Gmail MCP Server provides seamless Gmail access for Claude Code and other MCP-compatible clients. It lets you list, read, compose, and search emails, manage labels, and keeps emails threaded correctly for replies, all through a standardized MCP interface.

How to use

You connect to this Gmail MCP Server from your MCP client by configuring a server entry that points to the local runtime of the Gmail MCP Server. Once configured and running, you can list emails from folders like inbox or sent, fetch full email contents, compose or reply to messages with automatic send-signatures, and search using Gmail-style queries. You can also apply labels such as read, star, or archive to organize messages. Use the server to access Gmail programmatically from your MCP-enabled tooling without switching apps.

How to install

Prerequisites you need before installing the Gmail MCP Server:

Node.js 20 or higher
Google Cloud project with Gmail API enabled
OAuth 2.0 credentials (Desktop app type)

Step-by-step setup and installation commands:

# 1. Create a Google Cloud Project
# If you don’t have one yet
# - Create a project
# - Set it as active
# - Enable Gmail API

gcloud projects create your-project-name --name="Your MCP Tools"
gcloud config set project your-project-name
gcloud services enable gmail.googleapis.com

# 2. Configure OAuth Consent Screen
# Choose Internal for Google Workspace users or External for personal Gmail
# Add scopes: read-only, send, modify

# 3. Create OAuth Credentials
# Create an OAuth client ID for a Desktop app and download the JSON

# 4. Install and Build

git clone https://github.com/brentwpeterson/mcp-gmail.git
cd mcp-gmail
npm install
npm run build

# 5. Authenticate
npm run auth
# This opens a browser to approve permissions; tokens are saved to the local token store

# 6. Configure Your MCP Client
# Provide the runtime path to the built server in your MCP client config

Configuration and running the server

The server is configured as a standard MCP stdio server. You run it locally and point your MCP client at the script that starts the server.

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

Security and credentials

OAuth tokens and credentials are stored locally to keep your Gmail access separate from the MCP runner. Tokens live in your config directory and can be revoked at any time from your Google Account permissions. Protect access to your token and credentials files to prevent unauthorized use.

Notes and troubleshooting

If you encounter authentication issues, re-run the authentication flow to refresh tokens. Ensure the OAuth credentials JSON is saved to the configured path and that Gmail API access remains enabled for your project.

Available tools

gmail_list_emails

List recent emails with optional folder and search query to refine results.

gmail_get_email

Fetch the full content of a single email by ID.

gmail_send_email

Send a new email or reply to an existing thread using Gmail send capabilities with automatic signature.

gmail_search

Search emails using Gmail query syntax such as from:, to:, subject:, has:attachment, and date-based filters.

gmail_get_thread

Retrieve all messages within a conversation thread.

gmail_modify_labels

Add or remove labels like read, star, and archive on selected messages.

gmail_list_labels

List all available Gmail labels for the authenticated account.