Gmail MCP Server

Gmail MCP Server

Connect Claude to your Gmail account through the Model Context Protocol.

The Gmail MCP Server enables Claude to read emails, compose drafts, search threads, and interact with your inbox using natural language commands.

What Can Claude Do with the Gmail MCP Server?

The Gmail MCP Server exposes Gmail API functionality to Claude through the Model Context Protocol.

Core capabilities:

• Read Emails — Access message content, headers, and attachments metadata
• Compose Drafts — Create draft emails without sending
• Search Inbox — Find emails by sender, subject, date, or label
• Manage Labels — Apply, remove, or list Gmail labels
• Thread Management — Read email threads and conversation history

Access scope: Claude can only access Gmail data your OAuth credentials allow. The integration respects Gmail API permission scopes you grant during authorization.

How to Install the Gmail MCP Server

Installation requires Google OAuth credentials and Gmail API access.

Prerequisites

Before installing the MCP Server, you need:

1. A Google Cloud Platform account
2. A project with Gmail API enabled
3. OAuth 2.0 credentials (Client ID and Client Secret)

For Claude Code

A concrete current path is to use the maintained workspace-mcp Google Workspace server and expose only Gmail tools if that is all you need.

export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
claude mcp add google-workspace uvx workspace-mcp --tools gmail

For Claude Desktop

Add the same server to claude_desktop_config.json with your OAuth credentials:

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp", "--tools", "gmail"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration file.

Google OAuth Setup for Gmail MCP

The Gmail MCP Server requires OAuth 2.0 authentication.

Setting up OAuth credentials:

1. Create a Google Cloud Project

• Go to Google Cloud Console
• Create a new project or select an existing one

1. Enable Gmail API

• In your project, go to "APIs & Services" → "Library"
• Search for "Gmail API"
• Click "Enable"

1. Create OAuth 2.0 Credentials

• Go to "APIs & Services" → "Credentials"
• Click "Create Credentials" → "OAuth client ID"
• Choose application type (Desktop app or Web application)
• Configure the OAuth consent screen if prompted
• Download the credentials JSON file

1. Configure Required Scopes

The Gmail MCP Server requires specific OAuth scopes:

• https://www.googleapis.com/auth/gmail.readonly — Read-only access to emails
• https://www.googleapis.com/auth/gmail.compose — Create and send drafts
• https://www.googleapis.com/auth/gmail.modify — Read and modify emails (labels, archive)
• https://www.googleapis.com/auth/gmail.send — Send emails on your behalf

Minimum recommended scope: Use .gmail.readonly for read-only access, or .gmail.compose for draft creation without sending.

Sensitive scope warning: The .gmail.send scope allows sending emails directly. Use with extreme caution. Most use cases should focus on reading emails and creating drafts for manual review.

1. Complete OAuth Flow

The MCP Server will initiate an OAuth flow on first use. You'll be redirected to Google to authorize access. Follow the prompts to grant permissions.

OAuth token storage: The MCP Server stores refresh tokens securely for subsequent use. You only need to authorize once unless you revoke access.

Privacy considerations:

• Gmail contains sensitive personal and business communications
• Review requested scopes carefully during authorization
• Use read-only scopes unless modification is necessary
• Consider the sensitivity of allowing AI access to your inbox

Gmail MCP Use Cases & Email Automation Examples

Example workflows that become possible with the Gmail MCP Server.

Search Emails

Example prompt:

> "Find all emails from john@company.com received in the last 7 days."

Claude can search your inbox using Gmail's search operators.

Read Recent Messages

Example prompt:

> "Show me the subject lines of my 10 most recent unread emails."

Claude can retrieve and display email metadata.

Extract Information

Example prompt:

> "Find all emails with 'invoice' in the subject and extract the invoice numbers mentioned."

Claude can read email content and extract specific information.

Compose Drafts

Example prompt:

> "Create a draft email to team@company.com with subject 'Weekly Update' and a brief status summary."

Claude can compose draft emails for you to review and send manually.

Manage Labels

Example prompt:

> "Apply the label 'Follow-up' to all unread emails from last week."

Claude can organize emails using Gmail labels.

Search by Thread

Example prompt:

> "Show me the entire conversation thread for the email about the Q4 budget."

Claude can retrieve threaded email conversations.

Filter by Criteria

Example prompt:

> "Find emails with attachments larger than 5MB sent this month."

Claude can use advanced Gmail search filters.

Important: Email sending operations should be used with extreme caution. Always review drafts before sending. The safest workflow is to have Claude compose drafts that you manually review and send.

Note: These are example use cases. Actual capabilities depend on your OAuth permissions and the MCP server implementation. Read-only operations and draft creation are the safest use cases.

Use Gmail MCP in Verdent

Verdent provides streamlined Gmail integration with simplified OAuth setup. This is Verdent's platform-level integration flow, not the default setup path from Google's official documentation.

Connect your Gmail account once and access email operations across all Verdent projects without manual OAuth configuration. Verdent implements additional safeguards for email access and sending operations.

Connect Gmail in Verdent