Provides tools for interacting with Gmail to list, read, search, and send emails, as well as manage labels and conversation threads.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gmail MCP Serversearch for unread emails from Sarah about the project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
2. Configure OAuth Consent Screen
Select Internal (for Google Workspace) or External (for personal Gmail)
Add these scopes:
https://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/gmail.sendhttps://www.googleapis.com/auth/gmail.modify
3. Create OAuth 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
5. Authenticate
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):
Restart your MCP client to load the server.
Available Tools
Tool | Description |
| List recent emails with optional folder and search query |
| Get full content of a specific email |
| Send a new email or reply to a thread |
| Search emails using Gmail query syntax |
| Get all messages in a conversation |
| Add/remove labels (read, star, archive) |
| List all available labels |
Folder Options
The gmail_list_emails tool supports these folders:
Folder | Description |
| Inbox emails |
| Sent emails |
| Unread inbox emails |
| Starred emails |
| Important emails |
| Deleted emails |
| Spam folder |
| 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 senderto:user@example.com- To specific recipientsubject:meeting- Subject contains wordis:unread- Unread messagesis:starred- Starred messageshas:attachment- Has attachmentsnewer_than:2d- Newer than 2 daysolder_than:1w- Older than 1 weeklabel:work- Has specific label
Combine with spaces (AND) or OR: from:boss@work.com is:unread
Configuration
Environment variables (optional):
Variable | Description | Default |
| Config directory |
|
| Path to credentials.json |
|
How It Works
Signatures: Automatically fetched from your Gmail "Send mail as" settings
Thread Replies: Proper
In-Reply-ToandReferencesheaders for correct threadingSender Name: Uses your display name from Gmail settings
Security
OAuth tokens are stored locally in
~/.mcp-gmail/token.jsonCredentials 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