Gmail
Provides a suite of 17 tools for searching, reading, sending, and managing Gmail messages and drafts through the Model Context Protocol. It enables comprehensive email management including label organization, archiving, and attachment handling direct
What is Gmail?
Gmail is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to provides a suite of 17 tools for searching, reading, sending, and managing gmail messages and drafts through the model context protocol. it enables comprehensive email management including label organ...
Provides a suite of 17 tools for searching, reading, sending, and managing Gmail messages and drafts through the Model Context Protocol. It enables comprehensive email management including label organization, archiving, and attachment handling direct
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Provides a suite of 17 tools for searching, reading, sending
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcp-gmailConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Gmail
The mcp-gmail server provides 32 tools across six functional areas — authentication, labels, messages, attachments, threads, and drafts — giving AI assistants full programmatic access to Gmail through OAuth 2.0. All tools are prefixed with gmail_ and the server supports three access levels: read-only, write (adds send and draft), and destructive (enables delete and trash operations). It connects to Gmail via Google's official API and stores OAuth tokens locally, making it a private and auditable way to automate email workflows through Claude or any MCP-compatible client.
Prerequisites
- Node.js 22.0.0 or later installed
- A Google Cloud project with the Gmail API enabled
- OAuth 2.0 credentials (Client ID and Client Secret) from Google Cloud Console
- The compiled mcp-gmail distribution or source built with Bun 1.3+
- Claude Desktop or another MCP-compatible AI client
Create Google Cloud OAuth credentials
In Google Cloud Console, enable the Gmail API for your project, then create an OAuth 2.0 client ID of type 'Desktop app'. Download the credentials to get your Client ID and Client Secret.
# Google Cloud Console steps:
# 1. Go to APIs & Services > Library > search 'Gmail API' > Enable
# 2. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID
# 3. Application type: Desktop app
# 4. Copy the Client ID and Client SecretClone the repository and build the server
The server requires Bun to build from source. Clone the repository and compile the distribution.
git clone https://github.com/knowledgeislands/mcp-gmail.git
cd mcp-gmail
bun install
bun run buildAdd the server to Claude Desktop configuration
Edit claude_desktop_config.json to add the mcp-gmail server entry. Set your OAuth credentials as environment variables. Adjust the path to the compiled index.js in your clone directory.
{
"mcpServers": {
"mcp-gmail": {
"command": "node",
"args": ["/path/to/mcp-gmail/dist/mcp-server/index.js"],
"env": {
"MCP_GMAIL_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"MCP_GMAIL_CLIENT_SECRET": "your-client-secret",
"MCP_GMAIL_ACCESS_LEVEL": "write"
}
}
}
}Authenticate with Gmail on first use
On the first tool call, the server will open a browser window for OAuth consent. Sign in with your Google account, grant the requested Gmail permissions, and the token will be saved to ~/.mcp-gmail-tokens.json for future sessions.
Choose the appropriate access level
The MCP_GMAIL_ACCESS_LEVEL variable controls which tools are visible. Use 'read' for read-only access, 'write' to also enable send/draft tools, or 'destructive' to also expose delete and trash operations.
# Read-only (default): search, read, list labels and threads
# MCP_GMAIL_ACCESS_LEVEL=read
# Write: adds send, create draft, modify labels
# MCP_GMAIL_ACCESS_LEVEL=write
# Destructive: adds delete, trash, batch delete
# MCP_GMAIL_ACCESS_LEVEL=destructiveGmail Examples
Client configuration
Claude Desktop configuration for mcp-gmail with write access level and OAuth credentials.
{
"mcpServers": {
"mcp-gmail": {
"command": "node",
"args": ["/Users/you/mcp-gmail/dist/mcp-server/index.js"],
"env": {
"MCP_GMAIL_CLIENT_ID": "123456789-abc.apps.googleusercontent.com",
"MCP_GMAIL_CLIENT_SECRET": "GOCSPX-your-secret",
"MCP_GMAIL_ACCESS_LEVEL": "write",
"MCP_GMAIL_TOKEN_PATH": "/Users/you/.mcp-gmail-tokens.json"
}
}
}
}Prompts to try
Use natural language to search, read, send, and organize Gmail messages and threads.
- "Find all unread emails from GitHub notifications in the last 30 days and archive them"
- "Draft a reply to the meeting invite from Sarah about the Q3 planning session"
- "Search for emails with the label 'invoices' from the last 90 days and list them with sender and subject"
- "Move all emails labeled 'newsletters' to the 'reading-list' label and remove the old label"
- "List all my Gmail labels and show how many unread messages each has"Troubleshooting Gmail
OAuth authentication fails or browser does not open
Ensure MCP_GMAIL_REDIRECT_URI matches the redirect URI configured in Google Cloud Console. The default is http://localhost:3334/auth/callback — add this exact URI to the OAuth client's authorized redirect URIs in Google Cloud Console.
Token expires and tools stop working
The OAuth token stored at MCP_GMAIL_TOKEN_PATH includes a refresh token that should renew automatically. If it fails, delete the token file (default: ~/.mcp-gmail-tokens.json) and re-authenticate by triggering any Gmail tool in Claude Desktop.
Tools not appearing or missing send/delete capabilities
Check MCP_GMAIL_ACCESS_LEVEL in your config. The default is 'read', which hides write and destructive tools. Set it to 'write' or 'destructive' as needed, then restart Claude Desktop to reload the server.
Frequently Asked Questions about Gmail
What is Gmail?
Gmail is a Model Context Protocol (MCP) server that provides a suite of 17 tools for searching, reading, sending, and managing gmail messages and drafts through the model context protocol. it enables comprehensive email management including label organization, archiving, and attachment handling direct It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Gmail?
Follow the installation instructions on the Gmail GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Gmail?
Gmail works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Gmail free to use?
Yes, Gmail is open source and available under the Apache 2.0 license. You can use it freely in both personal and commercial projects.
Gmail Alternatives — Similar Communication Servers
Looking for alternatives to Gmail? Here are other popular communication servers you can use with Claude, Cursor, and VS Code.
Slack
★ 86.1kEnables interaction with Slack workspaces through comprehensive channel management, messaging, user management, file uploads, and Block Kit formatting. Features secure credential storage via macOS Keychain and supports all major Slack operations incl
LibreChat
★ 37.3kEnhanced ChatGPT Clone: Features Agents, MCP, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenA
Note Gen
★ 11.9kA cross-platform Markdown AI note-taking software.
DeepChat
★ 5.8k🐬DeepChat - A smart assistant that connects powerful AI to your personal world
WhatsApp MCP
★ 5.7kConnects AI assistants to the official Meta WhatsApp Cloud API for managing conversations and sending various message types through natural language. It provides tools for media management, template messages, and real-time webhook processing without
Apple
★ 3.1kEnables interaction with Apple apps like Messages, Notes, and Contacts through the MCP protocol to send messages, search, and open app content using natural language.
Browse More Communication MCP Servers
Explore all communication servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Gmail in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Gmail?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.