MCP Headless Gmail Server (NPM & Docker)

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

# Clone the repository
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -e .

Docker

Building the Docker Image

# Build the Docker image
docker build -t mcp-headless-gmail .

Usage with Claude Desktop

You can configure Claude Desktop to use the Docker image by adding the following to your Claude configuration:

docker

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

npm version

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@peakmojo/mcp-server-headless-gmail"
      ]
    }
  }
}

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):

   docker buildx create --use
   

2. Build and push the image for multiple platforms:

   docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
   

3. Verify the image is available for the specified platforms:

   docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest
   

Usage

The server provides Gmail functionality through MCP tools. Authentication handling is simplified with a dedicated token refresh tool.

Starting the S

... View full README on GitHub