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

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

File	Description
credentials.json	Optional — Override the built-in Google OAuth credentials with your own
token.json	Your Google OAuth tokens (auto-generated after authorization)
clients.json	Registered MCP clients (auto-generated)
access_tokens.json	Issued access tokens (auto-generated)

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

Tool	Description
list_emails	List emails from inbox with optional filters
read_email	Read full email content by ID
search_emails	Search using Gmail query syntax
send_email	Compose and send a new email
reply_to_email	Reply to an existing email
draft_email	Create a draft without sending
mark_as_read	Mark an email as read
mark_as_unread	Mark an email as unread
archive_email	Archive an email (remove from inbox)
trash_email	Move an email to trash
add_label	Add a label to an email
remove_label	Remove a label from an email
list_labels	List all Gmail labels
get_thread	Get all emails in a conversation
get_attachment	Download an email attachment

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

Endpoint	Description
GET /health	Health check & status
GET /.well-known/oauth-protected-resource	RFC 9728 metadata
GET /.well-known/oauth-authorization-server	RFC 8414 metadata
POST /oauth/register	Dynamic client registration
GET /oauth/authorize	Authorization endpoint
POST /oauth/token	Token endpoint
GET /sse	MCP SSE endpoint (protected)