Google Workspace Gmail MCP Server

Create a powerful Model Context Protocol (MCP) server for Gmail in minutes with our AI Gateway. This guide walks you through setting up seamless Gmail integration with enterprise-grade security and instant OAuth authentication.

About Gmail API

Gmail is Google's email service that serves over 1.8 billion users worldwide. The Gmail API provides programmatic access to Gmail mailboxes, enabling you to:

• Email Management: Read, send, modify, and organize emails programmatically
• Label System: Create and manage labels to organize emails effectively
• Thread Operations: Work with entire email conversations
• Attachment Handling: Upload and download attachments up to 25MB
• Search Capabilities: Use Gmail's powerful search syntax programmatically
• Draft Management: Create, update, and send email drafts
• Filter Creation: Automate email organization with filters
• Settings Access: Manage signatures, vacation responders, and forwarding

Key Features

• RESTful API: Standard HTTP methods for all operations
• Real-time Updates: Push notifications via Cloud Pub/Sub
• Batch Operations: Process multiple requests efficiently
• Full Unicode Support: Handle international content seamlessly
• OAuth 2.0 Security: Industry-standard authentication
• Rate Limiting: 250 quota units per user per second
• Message Size: Up to 25MB including attachments

What You Can Do with Gmail MCP Server

The MCP server transforms Gmail's API into a natural language interface, enabling AI agents to:

Email Operations

• Smart Email Management

  • "Show me all unread emails from my manager"
  • "Archive all promotional emails older than 30 days"
  • "Find emails with attachments from last week"

• Intelligent Composition

  • "Draft a professional response to this client inquiry"
  • "Create a follow-up email for all meeting participants"
  • "Generate a weekly summary email to my team"

• Automated Responses

  • "Reply to all support tickets with initial acknowledgment"
  • "Send personalized thank you notes to new customers"
  • "Create out-of-office responses based on calendar"

Organization & Labeling

• Smart Categorization

  • "Label all emails from vendors as 'Procurement'"
  • "Create a label system for project communications"
  • "Auto-categorize emails by sentiment and urgency"

• Bulk Operations

  • "Move all newsletters to a 'Reading' folder"
  • "Mark all emails from specific domain as important"
  • "Clean up emails older than retention policy"

Advanced Search & Analytics

• Intelligent Search

  • "Find all emails mentioning 'contract' with attachments"
  • "Show conversations about budget from Q4"
  • "List emails from customers expressing dissatisfaction"

• Email Analytics

  • "Analyze response times to customer emails"
  • "Generate report of email volume by sender domain"
  • "Track email engagement patterns"

AI-Powered Automation

• Smart Filtering

  • "Create filters based on email content patterns"
  • "Auto-forward specific types of requests to team members"
  • "Route emails based on sentiment analysis"

• Workflow Integration

  • "Extract action items from emails and create tasks"
  • "Sync important emails to CRM system"
  • "Generate calendar events from email invitations"

Business Intelligence

• Customer Insights

  • "Summarize all communications with specific client"
  • "Extract key topics from customer feedback emails"
  • "Identify trends in support requests"

• Team Collaboration

  • "Share email summaries in team channels"
  • "Create digest of important emails for executives"
  • "Monitor SLA compliance for support emails"

Prerequisites

• Access to Cequence AI Gateway
• Google Cloud Console account
• Gmail API enabled in your Google Cloud project
• Administrative access to create OAuth2 credentials

Step 1: Create Google OAuth2 Credentials

Before setting up the MCP server, you need to create OAuth2 credentials in Google Cloud Console.

1.1 Access Google Cloud Console

1. Navigate to Google Cloud Console
2. Select your project or create a new one
3. Ensure billing is enabled for your project

1.2 Enable Gmail API

1. Go to APIs & Services Library
2. Search for "Gmail API"
3. Click on Gmail API
4. Click Enable

1.3 Create OAuth2 Credentials

1. Navigate to APIs & Services Credentials

2. Click + CREATE CREDENTIALS OAuth client ID

3. If prompted, configure the OAuth consent screen first:

   • Choose Internal for organization use or External for broader access
   • Fill in the required fields:
     • App name: "AI Gateway Gmail Integration"
     • User support email: Your email
     • Developer contact: Your email
   • Add the required scopes (see Available Scopes section below)

4. Create the OAuth client:

   • Application type: Web application
   • Name: "AI Gateway Gmail MCP"
   • Authorized redirect URIs:

     https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

5. Save the credentials:

   • Download the JSON file
   • Note your Client ID and Client Secret

1.4 Configure Domain-Wide Delegation (Optional)

For Google Workspace domains:

1. Go to APIs & Services Credentials
2. Click on your OAuth2 client
3. Enable Domain-wide delegation
4. Note the Service Account Email
5. In Google Workspace Admin:
   • Go to Security API controls Domain-wide delegation
   • Add the client with Gmail scopes

Step 2: Access AI Gateway Apps

1. Log in to your Cequence AI Gateway dashboard
2. Navigate to Apps in the left sidebar
3. You'll see the list of available third-party applications

Step 3: Find and Select Gmail API

1. In the Apps section, browse through the Third-party category
2. Look for Google Workspace Gmail or use the search function
3. Click on the Gmail API card to view details

The Gmail API card shows:

• Number of available endpoints
• Integration capabilities
• Quick description of functionality

Step 4: Create MCP Server

1. Click the Create MCP Server button on the Gmail API card
2. You'll be redirected to the MCP Server creation wizard

Step 5: Configure API Endpoints

In the App Configuration step:

1. Base URL is pre-filled: https://gmail.googleapis.com
2. Select API endpoints to expose to your MCP server based on your needs
3. Click Next to proceed

Step 6: MCP Server Basic Setup

Configure your MCP server details:

1. MCP Server Name: Enter a descriptive name

   • Example: "Gmail Email Automation Server"
   • This name will identify your server in the dashboard

2. Description (Optional): Add details about the server's purpose

   • Example: "Automated email processing and response system for customer support"

3. Production Mode: Toggle based on your needs

   • ON for production environments
   • OFF for development/testing

4. Click Next to continue

Step 7: Configure Authentication

This is where you'll use your Google OAuth2 credentials:

1. Authentication Type: Select OAuth 2.0

2. Fill in the OAuth configuration:

   • Authorization URL:

     https://accounts.google.com/o/oauth2/auth

   • Token URL:

     https://accounts.google.com/o/oauth2/token

   • Client ID: Paste from Google Cloud Console
   • Client Secret: Paste from Google Cloud Console
   • Redirect URI:

     https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

3. Scopes: Select from the available Gmail scopes (see next section)

Available Gmail OAuth Scopes

Configure the appropriate scopes based on your application needs:

Read-Only Access

• https://www.googleapis.com/auth/gmail.readonly
  • View your email messages and settings
  • Search and retrieve email content
  • Access email metadata and headers
  • List labels and mailbox structure

Compose and Send

• https://www.googleapis.com/auth/gmail.compose

  • Create and send new email messages
  • Create drafts
  • Does NOT include ability to read existing emails

• https://www.googleapis.com/auth/gmail.send

  • Send email on your behalf
  • More restricted than compose - only sending, no draft creation
  • Ideal for automated notifications

Modify and Manage

• https://www.googleapis.com/auth/gmail.modify
  • Read, send, delete, and manage email
  • Modify labels and email metadata
  • Mark messages as read/unread
  • Move messages between folders
  • Does NOT include permanent deletion

Full Access

• https://mail.google.com/
  • Full access to Gmail mailbox
  • Includes all operations: read, send, delete, manage
  • Permanent deletion of emails and threads
  • Complete mailbox management
  • Use with caution - highest level of access

Recommended Scope Combinations

For Email Automation:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send

For Full Email Management:

https://www.googleapis.com/auth/gmail.modify

For Complete Integration:

https://mail.google.com/

Step 8: Configure Security

Set up API protection features:

1. API Protection: Toggle ON to enable

   • Protects against bot attacks, DDoS, and threats
   • Monitors for suspicious activity
   • Rate limiting and anomaly detection

2. Protection Features (when enabled):

   • Auto-scaling protection
   • Managed infrastructure
   • Built-in monitoring
   • Zero maintenance required

3. Click Next to continue

Step 9: Choose Deployment Method

Select your deployment preference:

Option A: Deploy to Cequence Cloud (Recommended)

• Fully managed deployment
• Automatic scaling and monitoring
• Built-in high availability
• Features included:
  • Auto-scaling
  • Managed infrastructure
  • Built-in monitoring
  • Zero maintenance

Option B: Deploy with Helm Chart

• Self-managed Kubernetes deployment
• Full control over infrastructure
• Requires:
  • Kubernetes cluster
  • Helm 3.x installed
  • Container registry access

Click Next after selecting your deployment method.

Step 10: Review and Deploy

Review your MCP server configuration:

• MCP Server Name: Your chosen name
• Base URL: https://gmail.googleapis.com
• Selected Endpoints: Number of endpoints selected
• Authentication: OAuth 2.0 (Configured)
• API Protection: Enabled/Disabled
• Deployment: Cequence Cloud or Helm

Click Create & Deploy to finalize the setup.

Step 11: Post-Deployment Setup

After successful deployment:

1. Note the MCP Server URL provided

2. Test the OAuth flow:

   • Click "Test Connection"
   • You'll be redirected to Google sign-in
   • Authorize the requested permissions
   • Confirm successful connection

3. Configure AI Agents:

   • The MCP server is now available for AI agent connections
   • Use the provided server URL in your AI agent configuration

Using Your Gmail MCP Server

With Claude Desktop

1. Open Claude Desktop settings

2. Add your MCP server:

   {
     "servers": {
       "gmail": {
         "url": "your-mcp-server-url",
         "auth": {
           "type": "oauth2",
           "client_id": "your-client-id"
         }
       }
     }
   }

3. Start using natural language commands:

   • "Show me unread emails from today"
   • "Draft a response to the latest email from John"
   • "Send a follow-up email to all participants in yesterday's meeting thread"
   • "Label all emails from support@company.com as 'Support'"
   • "Create a filter to automatically archive newsletters"

API Integration Example

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    token: 'user-access-token'
  }
});

// List recent emails
const emails = await mcpClient.gmail.messages.list({
  q: 'is:unread',
  maxResults: 10
});

// Send an email
await mcpClient.gmail.messages.send({
  to: 'recipient@example.com',
  subject: 'Automated Email',
  body: 'This email was sent via MCP server'
});

// Search emails
const searchResults = await mcpClient.gmail.messages.list({
  q: 'from:important@client.com has:attachment'
});

// Modify labels
await mcpClient.gmail.messages.modify({
  id: 'message-id',
  addLabelIds: ['IMPORTANT'],
  removeLabelIds: ['UNREAD']
});

Common Use Cases

Customer Support Automation

• Auto-categorize support tickets
• Generate draft responses
• Extract key information from emails
• Route emails to appropriate teams

Sales Automation

• Track email engagement
• Schedule follow-up emails
• Extract leads from email conversations
• Sync with CRM systems

Personal Productivity

• Smart email filtering
• Automated responses for common queries
• Email summarization
• Meeting invitation management

Security Best Practices

1. Scope Management:

   • Only request necessary scopes
   • Use read-only scopes when write access isn't needed
   • Regularly audit scope usage

2. Token Storage:

   • Never store tokens in code
   • Use secure credential management
   • Implement token rotation

3. Access Control:

   • Limit MCP server access to authorized users
   • Implement IP whitelisting if needed
   • Monitor access logs regularly

4. Data Protection:

   • Enable API protection features
   • Implement rate limiting
   • Set up alerts for unusual activity

Troubleshooting

Common Issues

1. OAuth Authorization Failed

   • Verify redirect URI matches exactly
   • Check client ID and secret
   • Ensure Gmail API is enabled
   • Confirm OAuth consent screen is configured

2. Insufficient Scopes Error

   • Add required scopes in Google Cloud Console
   • Update MCP server configuration
   • Re-authenticate users

3. Rate Limit Exceeded

   • Gmail API has quotas: 250 quota units per user per second
   • Implement exponential backoff
   • Use batch operations where possible
   • Monitor quota usage in Google Cloud Console

4. 403 Forbidden Errors

   • Check if user has granted all requested permissions
   • Verify domain-wide delegation if using service account
   • Ensure API is enabled in Google Cloud Console

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• Community: AI Gateway Forum
• Google Gmail API Docs: developers.google.com/gmail/api

---