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

Go to Google Cloud Console - OAuth Consent
Select Internal (for Google Workspace) or External (for personal Gmail)
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

Go to Google Cloud Console - Credentials
Click Create Credentials > OAuth client ID
Select Desktop app as the application type
Download the JSON file
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

mcp-gmail