mcp-headless-gmail

This MCP server provides Gmail access in a headless, remote-friendly manner. It exposes tools to get recent Gmail messages, fetch full email bodies in chunks, send emails, and refresh OAuth tokens without storing credentials locally. Clients (for example, Claude Desktop or other MCP clients) pass Google OAuth tokens and related data in the tool requests rather than embedding credentials in the server environment. The server itself maintains minimal state and handles token refreshing to keep access flowing securely. To use it, run the server through npm/published image options, then invoke the available MCP tools via your client, supplying the necessary credentials when prompted. The typical workflow involves first refreshing tokens when needed, then calling get-recent-emails or get-full-email-content, and finally sending emails through the Gmail API.

Prerequisites:

• Node.js (recommended: the LTS version) and npm installed on your system
• Internet access to fetch npm packages or access to Docker if you prefer the Docker path

Installation options:

1. Run via npx (no local install):

   • Prereqs: Node.js and npm
   • Command: npm install -g npx (if not already available), then: npx @peakmojo/mcp-server-headless-gmail

2. Install locally (recommended for development):

   • Clone or reference the package: npm install @peakmojo/mcp-server-headless-gmail
   • Start the server (example): npx @peakmojo/mcp-server-headless-gmail

3. Docker (alternative path):

   • Prerequisites: Docker installed
   • Build and run (from README examples): docker build -t mcp-headless-gmail . docker run -i --rm buryhuang/mcp-headless-gmail:latest

Note: For all methods, you will need Google API credentials (client ID, client secret, and tokens). The tooling expects these credentials to be supplied at call time or via the provided environment variables, not hard-coded in the server.

If you are deploying in Claude Desktop or another MCP client, configure the client to use the npx path shown above or the Docker image as described in the README.

Tips and caveats:

• This server expects Google OAuth tokens to be supplied by the client at call time; do not embed credentials in the server environment for security. The included token refresh flow helps maintain access without exposing credentials.
• When using Docker, ensure the container has access to any required network endpoints and that environment variables (client ID/secret) are provided at runtime if needed.
• The server supports chunked retrieval of large email bodies (1k chunk size). To reconstruct full content, sequentially fetch chunks by increasing the offset until contains_full_body is true.
• If you encounter token expiration errors, use the gmail_refresh_token tool with your client credentials to obtain a new access token.
• For best security, restrict Google API scopes to read-only and send-capable scopes as described in the credential obtaining steps.
• The npm package name used for MCP configuration is @peakmojo/mcp-server-headless-gmail; the docker image is buryhuang/mcp-headless-gmail or bur yhung/mcp-headless-gmail depending on the tag you choose.