Gmail MCP Server

An MCP (Model Context Protocol) server that provides Claude with access to your Gmail, featuring a full OAuth 2.1 authorization server with dynamic client registration.

Features

• Full OAuth 2.1 Authorization Server (RFC 8414, RFC 7591, RFC 9728)

• Dynamic Client Registration - Claude Code auto-registers

• PKCE Support (RFC 7636)

• First-class "Authenticate" button in Claude Code's /mcp menu

• Gmail tools: list, read, search, send, reply, draft, archive, trash, labels, attachments

Related MCP server: mcp-gmail

Prerequisites

Node.js 18+ is required. Install via nodejs.org or:

brew install node

Setup

1. Clone and install dependencies:

   git clone <repo-url> gmail-mcp
   cd gmail-mcp
   npm install

2. Build:

   npm run build

3. Start the server:

   npm start

   The server runs on http://localhost:3100 by default. Override with PORT=3200 npm start.

4. Configure Claude Code (~/.mcp.json):

   {
     "mcpServers": {
       "gmail": {
         "type": "sse",
         "url": "http://localhost:3100/sse"
       }
     }
   }

5. Authenticate via Claude Code:

   • Run /mcp in Claude Code

   • Click "Authenticate" on the gmail server

   • Complete Google OAuth in your browser

   Note: Google will show an "This app isn't verified" warning screen. This is normal for apps that haven't gone through Google's verification process. To proceed:

   1. Click Advanced

   2. Click Go to gmail-mcp (unsafe)

   3. Review the requested permissions (read and modify Gmail) and click Allow

   Your credentials are stored locally on your machine and are never sent to any third-party server.

Configuration

Google OAuth credentials are built in — no setup required. On first use, you'll be prompted to authorize your Gmail through Google's consent screen.

User-specific config files are stored in ~/.config/gmail-mcp/:

Auto-Start on Login (macOS)

Run the install script to set up the LaunchAgent:

./scripts/install.sh

This will:

• Detect your node installation

• Generate a plist with correct paths

• Install to ~/Library/LaunchAgents/

• Start the server immediately

To uninstall:

./scripts/uninstall.sh

Logs are written to ~/.config/gmail-mcp/stdout.log and stderr.log.

Available Tools

Gmail Search Syntax

The search_emails and list_emails tools support Gmail's query syntax:

• is:unread - Unread emails

• from:someone@example.com - From specific sender

• subject:invoice - Subject contains "invoice"

• has:attachment - Has attachments

• after:2025/01/01 - After a date

• before:2025/12/31 - Before a date

• label:important - Has specific label

Architecture

┌─────────────────┐      ┌──────────────────────────────────────┐
│   Claude Code   │◄────►│         Gmail MCP Server             │
│                 │ SSE  │                                      │
│  /mcp menu      │      │  ┌─────────────────────────────────┐ │
│  shows          │      │  │ OAuth 2.1 Authorization Server  │ │
│  "Authenticate" │      │  │  - Dynamic client registration  │ │
│                 │      │  │  - PKCE support                 │ │
└─────────────────┘      │  │  - Token management             │ │
                         │  └──────────────┬──────────────────┘ │
                         │                 │                    │
                         │  ┌──────────────▼──────────────────┐ │
                         │  │      Google OAuth Proxy         │ │
                         │  │  - Redirects to Google          │ │
                         │  │  - Stores Google tokens         │ │
                         │  └──────────────┬──────────────────┘ │
                         │                 │                    │
                         │  ┌──────────────▼──────────────────┐ │
                         │  │        Gmail API Tools          │ │
                         │  │  - list, read, search, etc.     │ │
                         │  └─────────────────────────────────┘ │
                         └──────────────────────────────────────┘

Development

npm run build   # Compile TypeScript
npm start       # Run server
npm run auth    # Standalone Google OAuth (alternative to browser flow)

Endpoints