baryhuang/mcp-headless-gmail

A MCP (Model Context Protocol) server that provides get, send Gmails without local credential or token setup.
Why MCP Headless Gmail Server?
Critical Advantages
- **Headless & Remote Operation**: Unlike other MCP Gmail solutions that require running outside of docker and local file access, this server can run completely headless in remote environments with no browser no local file access.
- **Decoupled Architecture**: Any client can complete the OAuth flow independently, then pass credentials as context to this MCP server, creating a complete separation between credential storage and server implementation.
Nice but not critical
- **Focused Functionality**: In many use cases, especially for marketing applications, only Gmail access is needed without additional Google services like Calendar, making this focused implementation ideal.
- **Docker-Ready**: Designed with containerization in mind for a well-isolated, environment-independent, one-click setup.
- **Reliable Dependencies**: Built on the well-maintained google-api-python-client library.
Features
- Get most recent emails from Gmail with the first 1k characters of the body
- Get full email body content in 1k chunks using offset parameter
- Send emails through Gmail
- Refresh access tokens separately
- Automatic refresh token handling
Prerequisites
- Python 3.10 or higher
- Google API credentials (client ID, client secret, access token, and refresh token)
Installation
Docker
Building the Docker Image
Usage with Claude Desktop
You can configure Claude Desktop to use the Docker image by adding the following to your Claude configuration:
docker
npm version
Note: With this configuration, you'll need to provide your Google API credentials in the tool calls as shown in the Using the Tools section. Gmail credentials are not passed as environment variables to maintain separation between credential storage and server implementation.
Cross-Platform Publishing
To publish the Docker image for multiple platforms, you can use the docker buildx command. Follow these steps:
1. **Create a new builder instance** (if you haven't already):
2. **Build and push the image for multiple platforms**:
3. **Verify the image is available for the specified platforms**:
Usage
The server provides Gmail functionality through MCP tools. Authentication handling is simplified with a dedicated token refresh tool.
Starting the Server
Using the Tools
When using an MCP client like Claude, you have two main ways to handle authentication:
Refreshing Tokens (First Step or When Tokens Expire)
If you have both access and refresh tokens:
If your access token has expired, you can refresh with just the refresh token:
This will return a new access token and its expiration time, which you can use for subsequent calls.
Getting Recent Emails
Retrieves recent emails with the first 1k characters of each email body:
Response includes:
- Email metadata (id, threadId, from, to, subject, date, etc.)
- First 1000 characters of the email body
- body_size_bytes: Total size of the email body in bytes
- contains_full_body: Boolean indicating if the entire body is included (true) or truncated (false)