MCP Headless Gmail Server
by baryhuang
A Model Context Protocol (MCP) server that provides get and send Gmail functionalities without requiring local credential or token setup. It enables headless and remote operation, decoupling credential storage from server implementation.
Last updated: N/A
What is MCP Headless Gmail Server?
This is an MCP server designed to interact with Gmail, allowing users to send and retrieve emails without needing local credentials or token management within the server itself. It's designed to run in a headless environment, such as a Docker container, and focuses on providing essential Gmail functionalities.
How to use MCP Headless Gmail Server?
To use the server, you'll need to obtain Google API credentials (client ID, client secret, access token, and refresh token). You can then start the server and use the provided tools to refresh tokens, get recent emails, retrieve full email bodies, and send emails. The server interacts with MCP clients like Claude, where you provide the credentials in the tool calls.
Key features of MCP Headless Gmail Server
Headless & Remote Operation
Decoupled Architecture
Focused Functionality (Gmail only)
Docker-Ready
Automatic refresh token handling
Ability to get recent emails with body snippets
Ability to retrieve full email body content in chunks
Ability to send emails
Use cases of MCP Headless Gmail Server
Automated email sending from serverless environments
Integrating Gmail functionality into AI assistants like Claude
Marketing applications requiring only Gmail access
Running Gmail-related tasks in Docker containers
Securely managing Gmail credentials separately from the server implementation
FAQ from MCP Headless Gmail Server
What are the prerequisites for using this server?
What are the prerequisites for using this server?
Python 3.10 or higher and Google API credentials (client ID, client secret, access token, and refresh token).
How do I obtain Google API credentials?
How do I obtain Google API credentials?
Go to the Google Cloud Console, create a new project, enable the Gmail API, configure the OAuth consent screen, create OAuth client ID credentials, and save the client ID and client secret. Then, use OAuth 2.0 to obtain access and refresh tokens with the necessary scopes.
How do I refresh access tokens?
How do I refresh access tokens?
Use the gmail_refresh_token tool with either your full credentials (access token, refresh token, client ID, and client secret) or just your refresh token, client ID, and client secret if the access token has expired.
How do I get the full email body content?
How do I get the full email body content?
For emails with bodies larger than 1k characters, use the tool to retrieve the full content in chunks by making sequential calls increasing the offset by 1000 each time until contains_full_body is true.
Is this server secure?
Is this server secure?
This server requires direct access to your Google API credentials. Always keep your tokens and credentials secure and never share them with untrusted parties.