Gmail MCP Server

An MCP server that lets AI agents search Gmail threads, understand your email writing style, and create draft emails.

1. Get Google Authentication

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" dropdown at the top
3. Click "New Project"
4. Enter a project name (e.g., "Gmail MCP Server")
5. Click "Create"

Step 2: Enable Gmail API

1. In your new project, go to "APIs & Services" → "Library"
2. Search for "Gmail API"
3. Click on "Gmail API" and click "Enable"

Step 3: Create OAuth2 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth Client ID"
3. If prompted, configure the OAuth consent screen:
   • Choose "External" user type
   • Fill in required fields (App name, User support email, Developer email)
   • Add your email to "Test users" section
   • Save and continue through all steps
4. Back in Credentials, click "Create Credentials" → "OAuth Client ID"
5. Choose "Desktop application" as the application type
6. Enter a name (e.g., "Gmail MCP Client")
7. Click "Create"
8. Important: Copy the Client ID and Client Secret from the confirmation dialog (you'll need these for configuration)

Step 4: Grant OAuth Scopes

When you first run the server, it will open your browser for authorization. The server requests only these minimal permissions:

What We Request:

• ✅ Gmail Readonly Access (gmail.readonly)

  • Search and read your email messages
  • Download email attachments
  • View email metadata (subjects, senders, dates)

• ✅ Gmail Compose Access (gmail.compose)

  • Create email drafts
  • Update existing drafts
  • Delete drafts
  • Send emails (permission granted but not used by this server)

What This Server Actualy Implements:

• ✅ Search and read emails - Full search capabilities
• ✅ Extract attachment text - Safe PDF/DOCX/TXT text extraction
• ✅ Create/update drafts - Smart draft management with thread awareness
• ❌ Send emails - Server doesn't implement sending (though permission is granted)
• ❌ Delete emails - Server doesn't implement deletion
• ❌ Modify labels - Server doesn't implement label management

2. Add to MCP Clients

Build the server first: go build .

You'll want to add this to your agent's configuration file:

{
  "mcpServers": {
    "gmail": {
      "command": "C:/path/to/your/auto-gmail.exe",
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id_here.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret_here",
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

⚡ Persistent HTTP Mode (Recommended to Avoid OAuth Popups)

Problem: In stdio mode, Cursor starts a fresh server process each time (and for each tab), causing OAuth popup spam.

Solution: Run the server as a persistent HTTP daemon that authenticates once and stays running.

Quick Start:

# Build the server
go build -o gmail-mcp-server

# Start persistent server (OAuth only once!)
./gmail-mcp-server --http

# Or with custom port
./gmail-mcp-server --http 3000

What Happens:

1. ✅ OAuth popup appears ONCE when server starts
2. ✅ Server runs persistently on http://localhost:8080
3. ✅ No more OAuth popups - server stays authenticated
4. ✅ Multiple Cursor tabs/windows can connect to same server

Cursor Configuration (Still Use stdio for now):

{
  "mcpServers": {
    "gmail": {
      "command": "C:/path/to/your/gmail-mcp-server",
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id_here.apps.googleusercontent.com", 
        "GMAIL_CLIENT_SECRET": "your_client_secret_here",
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

The difference: You start the server manually once instead of letting Cursor start it fresh each time.

Server Status:

• Visit http://localhost:8080 to see server status
• Health check: http://localhost:8080/health
• View available tools and configuration examples

Add to Cursor

• Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
• Click the MCP-tab
• Click '+ Add new global MCP server'
• Edit config file

Add to Claude Desktop

• Go to File > Settings > Developer > Edit Config
• Edit Config file

Manual Configuration Alternative:

You can edit these config files directly if you know where to find them:

• Cursor: C:\Users\[User]\.cursor\mcp.json
• Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows)

3. MCP Tools and Resources

Tools:

• search_threads - Search Gmail with queries like "from:[email protected]" or "subject:meeting" (includes draft info)
• create_draft - Create email drafts or update existing drafts (AI will request style guide first)
• extract_attachment_by_filename - Safely extract text from PDF, DOCX, and TXT attachments using filename
• get_personal_email_style_guide - Get your email writing style guide (this is a temporary tool, created because most agents do not yet support fetching resources--once agents implement MCP resources better, then thsi tool can be removed)

Resources:

• file://personal-email-style-guide - Your personal email writing style (auto-generated or manual)

Prompts:

• /generate-email-tone - Analyze your sent emails to create personalized writing style
• /server-status - Show file locations and server status

4. Personal Email Style Guide

The server will create a style-guide file based on the last 25 emails you've sent, so that newly drafted emails will hopefully sound like you. Honestly, so far LLM-written emails still don't sound very authentic.

Manual Generation:

• Run /generate-email-tone prompt in your MCP client anytime to regenerate
• The file is saved to your app data directory (see File Storage Locations above)

AI Integration:

• AI always calls get_personal_email_style_guide tool before writing emails
• Ensures consistent personal style across all communications
• Resource also available at file://personal-email-style-guide

5. Alternative way to Setup Environment Variables

If you want to run this MCP server outside of an agent, you can create a .env file based on the .env.example file and supply the environment variables that way, or export them into your environment prior to running:

export GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
export GMAIL_CLIENT_SECRET=your_client_secret_here
export OPENAI_API_KEY=your_openai_api_key_here

6. File Storage Locations

The server stores authentication and configuration files in standard application directories:

File Locations:

• Windows: C:\Users\[YourUsername]\AppData\Roaming\auto-gmail\
• Mac: ~/.auto-gmail/
• Linux: ~/.auto-gmail/

Important Files:

• token.json - OAuth authentication token (auto-generated)
• personal-email-style-guide.md - Your email writing style guide (auto-generated or manual)

Quick Commands:

• Use /server-status in your MCP client to see exact file paths
• Delete token.json to force re-authentication with updated permissions

7. TODOs

• Improve OAuth login flow - ✅ SOLVED! Use persistent HTTP mode (./gmail-mcp-server --http) to avoid OAuth popups. Server authenticates once and stays running.
• Full HTTP MCP Transport - Waiting for mark3labs/mcp-go to expose complete HTTP transport APIs
• Better Email Authenticity - LLM-written emails still don't sound perfectly authentic despite style guides