Overview
What is gmail-mcp-server?
A server that exposes the Gmail API through the Model Context Protocol (MCP), designed for integration with LLMs and use in environments like Claude Desktop.
How to use gmail-mcp-server?
Install Python 3.11+, clone the repository, and use uv pip install -r uv.lock to manage dependencies. Build and install the package locally with uv run -m build then uv pip install dist/gmail_mcp_server-*.whl. Obtain Google OAuth credentials and set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET as environment variables. Configure Claude Desktop by adding the executable path and credentials in its JSON configuration file.
Key features of gmail-mcp-server
- Get all Gmail labels
- Get, create, update, and delete labels
- Mark emails as read or unread
- Add labels to multiple emails
- Search emails with pagination via Gmail query
- Retrieve full email details by ID
Use cases of gmail-mcp-server
- Automate email organization by creating and applying labels
- Bulk mark emails as read/unread for inbox management
- Search and retrieve specific emails for LLM-driven analysis
- Integrate Gmail actions into AI assistant workflows (e.g., Claude Desktop)
FAQ from gmail-mcp-server
What are the runtime requirements?
Python 3.11 or higher and the uv dependency manager are required. Optional tools include build for packaging and Claude Desktop for integration.
How do I obtain Google OAuth credentials?
Create an OAuth 2.0 client ID in the Google Cloud Console (desktop application type), enable the Gmail API, and use the client ID and secret as environment variables.
Where does authentication data live?
Credentials are provided as environment variables (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) and are not stored by the server. OAuth tokens are managed by Google's client library at runtime.
How do I integrate this server with Claude Desktop?
Add the server executable path and credentials to claude.config.json under mcpServers.gmail, setting the command to either the full path to the executable or gmail-mcp-server if it's on the PATH.
What transport does the server use?
The server uses the standard MCP command-line interface transport (stdio) when launched by a client like Claude Desktop.
