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:/

... View full README on GitHub