Gmail
Enables intelligent integration with Gmail and Google Calendar for context-aware email analysis, advanced searching, and personalized response drafting. It supports natural language interactions for managing communication history, detecting events in
What is Gmail?
Gmail is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to enables intelligent integration with gmail and google calendar for context-aware email analysis, advanced searching, and personalized response drafting. it supports natural language interactions for m...
Enables intelligent integration with Gmail and Google Calendar for context-aware email analysis, advanced searching, and personalized response drafting. It supports natural language interactions for managing communication history, detecting events in
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Enables intelligent integration with Gmail and Google Calend
Use Cases
Maintainer
Works with
Installation
NPM
npx -y gmail-mcpManual Installation
npx -y gmail-mcpConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Gmail
This Gmail MCP server connects AI assistants to your Google Gmail account, enabling operations such as reading unread emails, sending new messages, trashing emails, and opening messages in the browser. It uses OAuth 2.0 for authentication and is designed to prompt for user confirmation before taking any destructive or send action, making it suitable for augmenting email workflows with AI assistance.
Prerequisites
- Python 3.10+ and uv package manager installed
- A Google Cloud project with the Gmail API enabled and an OAuth 2.0 Client ID (Desktop App) downloaded as a JSON credentials file
- A personal Gmail account added as a Test User in the Google Cloud OAuth consent screen
- An MCP-compatible client such as Claude Desktop
Create a Google Cloud project and enable Gmail API
Go to the Google Cloud Console, create a new project, and enable the Gmail API. Under APIs & Services, configure an OAuth consent screen (External), add your personal email as a Test User, and add the scope https://www.googleapis.com/auth/gmail.modify.
Create OAuth credentials and download the JSON file
In Google Cloud Console go to APIs & Services → Credentials, create an OAuth Client ID of type 'Desktop App', then download the JSON key file. Save it to a secure location such as ~/.google/client_creds.json.
Clone the repository and install dependencies
Clone the gmail-mcp-server repository and use uv to install the Python dependencies.
git clone https://github.com/jasonsum/gmail-mcp-server.git
cd gmail-mcp-server
uv syncRun the server once to complete OAuth authentication
Start the server with the paths to your credentials and token files. A browser window will open for Google OAuth authorization. The resulting tokens are saved to the token path for future use.
uv run gmail --creds-file-path ~/.google/client_creds.json --token-path ~/.google/app_tokens.jsonAdd the server to your MCP client configuration
Open your Claude Desktop config file at ~/Library/Application Support/Claude/claude_desktop_config.json and add the server entry. Replace the directory and credential paths with your actual absolute paths.
{
"mcpServers": {
"gmail": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/gmail-mcp-server",
"run",
"gmail",
"--creds-file-path",
"/Users/your-username/.google/client_creds.json",
"--token-path",
"/Users/your-username/.google/app_tokens.json"
]
}
}
}Gmail Examples
Client configuration
Claude Desktop configuration for the Gmail MCP server using uv as the runner. All paths must be absolute.
{
"mcpServers": {
"gmail": {
"command": "uv",
"args": [
"--directory",
"/Users/your-username/gmail-mcp-server",
"run",
"gmail",
"--creds-file-path",
"/Users/your-username/.google/client_creds.json",
"--token-path",
"/Users/your-username/.google/app_tokens.json"
]
}
}
}Prompts to try
Natural language prompts to use with the Gmail MCP server once it is connected.
- "Show me my unread emails"
- "Send an email to [email protected] with subject 'Meeting Tomorrow' and a brief message"
- "Trash the email with ID <email_id>"
- "Read the full content of my latest unread email"
- "Open the most recent email from [email protected] in my browser"Troubleshooting Gmail
OAuth browser window does not open or authentication fails
Ensure your Google Cloud project has the Gmail API enabled and your personal email is added as a Test User under the OAuth consent screen. The app does not need to be published; Test User status is sufficient for personal use.
Server fails to start with 'module not found' or import errors
Make sure you are running the server from the cloned repository directory with 'uv sync' completed. The --directory argument in the MCP config must be the absolute path to the gmail-mcp-server folder containing the pyproject.toml.
Token expires or refresh fails after some days
Delete the file at your --token-path and restart the server to trigger a fresh OAuth authentication flow. The new tokens will be saved automatically.
Frequently Asked Questions about Gmail
What is Gmail?
Gmail is a Model Context Protocol (MCP) server that enables intelligent integration with gmail and google calendar for context-aware email analysis, advanced searching, and personalized response drafting. it supports natural language interactions for managing communication history, detecting events in It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Gmail?
Install via npm with the command: npx -y gmail-mcp. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
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 GPL 3.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.