Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail access for Claude Code and other MCP-compatible clients.

Features

• List emails from any folder (inbox, sent, unread, starred, etc.)
• Read full email content
• Send emails with automatic signature
• Reply to threads with proper threading headers
• Search using Gmail's query syntax
• Manage labels (star, archive, mark read/unread)

Prerequisites

• Node.js 20 or higher
• A Google Cloud project with Gmail API enabled
• OAuth 2.0 credentials (Desktop app type)

Setup

1. Create a Google Cloud Project

If you don't have one already:

gcloud projects create your-project-name --name="Your MCP Tools"
gcloud config set project your-project-name
gcloud services enable gmail.googleapis.com

2. Configure OAuth Consent Screen

1. Go to Google Cloud Console - OAuth Consent
2. Select Internal (for Google Workspace) or External (for personal Gmail)
3. Add these scopes:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.modify

3. Create OAuth Credentials

1. Go to Google Cloud Console - Credentials
2. Click Create Credentials > OAuth client ID
3. Select Desktop app as the application type
4. Download the JSON file
5. Save it as ~/.mcp-gmail/credentials.json

4. Install and Build

git clone https://github.com/brentwpeterson/mcp-gmail.git
cd mcp-gmail
npm install
npm run build

5. Authenticate

npm run auth

This opens a browser for Google OAuth. Approve the permissions, and tokens will be saved to ~/.mcp-gmail/token.json.

6. Configure Your MCP Client

Add to your MCP configuration file (e.g., .mcp.json for Claude Code):

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gmail/dist/index.js"]
    }
  }
}

Restart your MCP client to load the server.

Available Tools

Tool	Description
gmail_list_emails	List recent emails with optional folder and search query
gmail_get_email	Get full content of a specific email
gmail_send_email	Send a new email or reply to a thread
gmail_search	Search emails using Gmail query syntax
gmail_get_thread	Get all messages in a conversation
gmail_modify_labels	Add/remove labels (read, star, archive)
gmail_list_labels	List all available labels

Folder Options

The gmail_list_emails tool supports these folders:

Folder	Description
inbox (default)	Inbox emails
sent	Sent emails
unread	Unread inbox emails
starred	Starred emails
important	Important emails
trash	Deleted emails
spam	Spam folder
all	All emails (no filter)

Gmail Search Syntax

The gmail_search tool and query parameter support Gmail's search syntax:

• from:user@example.com - From specific sender
• to:user@example.com - To specific recipient
• subject:meeting - Subject contains word
• is:unread - Unread messages
• is:starred - Starred messages
• has:attachment - Has attachments
• newer_than:2d - Newer than 2 days
• older_than:1w - Older than 1 week
• label:work - Has specific label

Combine with spaces (AND) or OR: from:boss@work.com is:unread

Configuration

Environment variables (optional):

Variable	Description	Default
GMAIL_CONFIG_DIR	Config directory	~/.mcp-gmail
GMAIL_CREDENTIALS_PATH	Path to credentials.json	~/.mcp-gmail/credentials.json

How It Works

• Signatures: Automatically fetched from your Gmail "Send mail as" settings
• Thread Replies: Proper In-Reply-To and References headers for correct threading
• Sender Name: Uses your display name from Gmail settings

Security

• OAuth tokens are stored locally in ~/.mcp-gmail/token.json
• Credentials and tokens are never committed (see .gitignore)
• Only you can access your email through this server
• Tokens can be revoked at any time from Google Account Permissions

License

MIT