home / mcp / gmail mcp server

Gmail MCP Server

A MCP (Model Context Protocol) server that provides get, send Gmails without local credential or token setup.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can run a headless MCP Gmail server that handles getting recent emails, fetching full email bodies in chunks, sending emails, and managing token refreshes, all without local credentials stored on the server. It’s designed to operate remotely in containers or via single-command tools, keeping credential storage separate from the server logic while enabling secure Gmail access.

How to use

You integrate the MCP Gmail server with a client that supports MCP configurations. You can start the server locally or in a container, then issue MCP calls to fetch emails, read message bodies in chunks, or send emails using the Gmail API. The server handles token refreshes automatically, so you don’t have to manage access tokens for every request.

How to install

Prerequisites: Python 3.10 or higher, and Google API credentials (client ID, client secret, access token, and refresh token). You can also run the server via container tools or through an MCP-friendly runner.

Step 1: Install via container/runtime helper (Docker example) or an MCP-enabled CLI.

# Starting a Docker-based runtime for the MCP Gmail server
# This runs the image and keeps it interactive
# You can adapt the command for your environment as needed
docker run -i --rm buryhuang/mcp-headless-gmail:latest

Usage with MCP clients and quick start

To run from a container using a generic MCP runner, you can configure the client to execute the appropriate runtime command for the service. The following runtime commands are shown as integration options:

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

Starting the server directly

If you prefer to run the server directly as a local process, you can use the standard start command shown in the examples.

mcp-server-headless-gmail

Tools and typical workflows

Typical workflows include refreshing tokens, retrieving recent emails, obtaining full bodies in chunks, and sending emails. The server supports automatic token refreshing so you can keep using the Gmail API without manual re-authentication.

Notes on credentials and security

Gmail credentials are not passed as environment variables to maintain separation between credential storage and server implementation. You provide credentials in your tool calls when you perform operations.

Security considerations

Keep your Google API credentials secure and limit access to the containers or hosts running the MCP Gmail server. Rotate tokens as needed and follow best practices for secret management in your environment.

Additional setup notes

To obtain Google API credentials, set up a project in your Google Cloud Console, enable Gmail API, configure OAuth consent, and generate Desktop-type OAuth credentials. Use scopes for reading and sending Gmail messages as required.

Available tools

get_recent_emails

Fetch the most recent Gmail messages, returning metadata and the first 1000 characters of each body.

get_full_body_chunk

Retrieve the full email body content in 1000-character chunks by specifying an offset or thread id.

send_email

Send an email via Gmail by providing recipient, subject, and body content (plain or HTML).

gmail_refresh_token

Refresh access tokens using the refresh token when needed, returning a new access token and expiry.

token_auto_refresh

Automatic handling of token refreshes to minimize manual credential management.