Headless Gmail
A headless server that enables reading and sending Gmail emails through API calls without requiring local credentials or browser access, designed to run remotely in containerized environments.
What is Headless Gmail?
Headless Gmail is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to headless server that enables reading and sending gmail emails through api calls without requiring local credentials or browser access, designed to run remotely in containerized environments.
A headless server that enables reading and sending Gmail emails through API calls without requiring local credentials or browser access, designed to run remotely in containerized environments.
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A headless server that enables reading and sending Gmail ema
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcp-headless-gmail-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Headless Gmail
MCP Headless Gmail is a Python-based MCP server that enables AI assistants to read and send Gmail emails entirely through API calls, without requiring a local browser session or stored credentials on the server. Instead of environment variables, Google OAuth credentials (access token, refresh token, client ID, and client secret) are passed directly as parameters in each tool call, making the server safe to run in containerized or remote environments. It is designed for automation scenarios where Gmail access needs to be integrated into AI workflows running in cloud infrastructure.
Prerequisites
- A Google Cloud project with the Gmail API enabled and an OAuth 2.0 client ID configured
- Google OAuth credentials: client_id, client_secret, refresh_token, and a valid access_token
- Docker installed (recommended for containerized deployment) OR Python 3.10+ with pip
- Claude Desktop or another MCP-compatible AI client
- Gmail account with API access authorized through the OAuth consent screen
Enable Gmail API and create OAuth credentials
In Google Cloud Console, create a project, enable the Gmail API, and create an OAuth 2.0 client ID (Desktop app type). Download the credentials JSON. Complete the OAuth flow once to obtain a refresh token using the Google OAuth Playground or a script.
Pull the Docker image
Pull the pre-built Docker image for the headless Gmail server. This is the recommended approach for running in containerized environments.
docker pull buryhuang/mcp-headless-gmail:latestAlternative: install from source with pip
If not using Docker, clone the repository and install the Python package directly.
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail
pip install -e .Configure Claude Desktop
Add the headless Gmail server to your Claude Desktop config. Credentials are passed per-call rather than in env vars, so no secrets are needed in the config file itself.
{
"mcpServers": {
"gmail": {
"command": "docker",
"args": ["run", "-i", "--rm", "buryhuang/mcp-headless-gmail:latest"]
}
}
}Use the token refresh tool before reading email
On first use, call the gmail_refresh_token tool with your refresh token and client credentials to get a fresh access token. Then use that access token in subsequent get_recent_emails and send_email calls.
Headless Gmail Examples
Client configuration
Claude Desktop configuration using the Docker image for MCP Headless Gmail. No credentials in the config — they are passed per tool call.
{
"mcpServers": {
"gmail": {
"command": "docker",
"args": ["run", "-i", "--rm", "buryhuang/mcp-headless-gmail:latest"]
}
}
}Prompts to try
Example prompts for reading and sending Gmail through Claude after providing your OAuth credentials.
- "Refresh my Gmail access token using my refresh token and client credentials"
- "Get my 5 most recent emails"
- "Show me only unread emails from the last 24 hours"
- "Read the full body of the email from John about the project proposal"
- "Send an email to [email protected] with subject 'Meeting Notes' and the summary we just discussed"
- "Get the full content of the third email in chunks"Troubleshooting Headless Gmail
Access token expired error when fetching emails
Access tokens expire after 1 hour. Use the gmail_refresh_token tool first, passing your google_refresh_token, google_client_id, and google_client_secret. The tool returns a new access token to use in subsequent calls. You do not need to re-authorize the OAuth flow.
OAuth consent screen shows 'App not verified' warning
This is normal for personal/internal Google Cloud projects. Click 'Advanced' > 'Go to [your app] (unsafe)' to proceed during the initial authorization flow. The warning only appears during the one-time setup, not during normal MCP server operation.
Docker container exits immediately when added to Claude Desktop
Ensure the -i (interactive/stdin) flag is present in your Docker args. MCP servers communicate over stdin/stdout, and without -i the container will exit as soon as it starts because stdin is closed.
Frequently Asked Questions about Headless Gmail
What is Headless Gmail?
Headless Gmail is a Model Context Protocol (MCP) server that headless server that enables reading and sending gmail emails through api calls without requiring local credentials or browser access, designed to run remotely in containerized environments. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Headless Gmail?
Follow the installation instructions on the Headless Gmail GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Headless Gmail?
Headless Gmail works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Headless Gmail free to use?
Yes, Headless Gmail is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Headless Gmail Alternatives — Similar Communication Servers
Looking for alternatives to Headless 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 Headless 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 Headless Gmail?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.