Advertise
MCP.so
Sign In

MCP Headless Gmail Server

@baryhuang

Repository

Basic information

Category

Communication

License

MIT

Transports

stdio

Author

baryhuang

About MCP Headless Gmail Server

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

#mcp#gmail#google-suite#gmail-bot#ai-assistant#mcp-server

MCP Headless Gmail Server config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mcp-headless-gmail": {
      "command": "docker",
      "args": [
        "build",
        "-t",
        "mcp-headless-gmail",
        "."
      ]
    }
  }
}

MCP Headless Gmail Server tools

Tool list not available yet

This listing does not currently have a tool list to display. This does not mean the server has no tools; check its documentation for supported capabilities.

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is MCP Headless Gmail Server?

A Model Context Protocol (MCP) server that provides get, send, and refresh Gmail functionality without requiring local credential or token setup. It is designed for headless, remote environments and decouples credential storage from server implementation.

How to use MCP Headless Gmail Server?

Install via pip install -e . or use the Docker image buryhuang/mcp-headless-gmail:latest. Configure an MCP client like Claude Desktop with either the Docker or npx command shown in the README. Provide your Google API credentials (client ID, client secret, access token, refresh token) via tool calls. Start by refreshing the token with gmail_refresh_token, then use tools such as get_recent_emails, get_email_body, and send_email.

Key features of MCP Headless Gmail Server

  • Get recent emails with first 1k characters of body.
  • Retrieve full email body in 1k-character chunks via offset.
  • Send emails through Gmail with plain text or HTML body.
  • Refresh access tokens separately or automatically when expired.
  • Run completely headless in remote environments (no browser, no local files).
  • Docker-ready for isolated, one-click deployment.

Use cases of MCP Headless Gmail Server

  • Automate reading and responding to emails from an AI assistant.
  • Send Gmail messages directly from MCP-enabled clients like Claude Desktop.
  • Integrate Gmail access into marketing or notification workflows without local credential storage.
  • Deploy a stateless Gmail service in containerised or cloud environments.

Frequently asked questions

1

What are the prerequisites?

Python 3.10 or higher and Google API credentials (client ID, client secret, access token, and refresh token).

2

How do I obtain Google API credentials?

Create a project in the Google Cloud Console, enable the Gmail API, configure the OAuth consent screen, create an OAuth client ID (Desktop app type), and use OAuth 2.0 to obtain tokens with scopes `gmail.readonly` and `gmail.send`.

3

How does token refresh work?

The server provides a `gmail_refresh_token` tool that accepts either full credentials or just a refresh token with client ID/secret. It returns a new access token. Automatic refresh is also handled by the underlying Google API client when the access token expires.

4

Can this server run inside Docker?

Yes. The Docker image can be built with `docker build -t mcp-headless-gmail .` and run with a `docker run` command. Configuration for Claude Desktop using Docker is provided in the README.

5

What scopes are required for the Gmail API?

The server requires `https://www.googleapis.com/auth/gmail.readonly` for reading emails and `https://www.googleapis.com/auth/gmail.send` for sending emails.

Comments

More Communication MCP servers

SendRaven

CommonNinja

SendRaven is email infrastructure for AI agents. Send, read replies as threads, run campaigns and automations, with limits on the API key.

1

SomaCheck Vibecheck

Sensie-agents

Body language for AI agents, on your terms. A consented three-second phone gesture gives your agent an Aligned or Unaligned signal with confidence. You remain the authority.

1

Surgemesh

Novus Index LLC

Agent-first social publishing: exact quotes, then posts across networks, paid per post from prepaid credit. Remote MCP. Preview: quotes and sandbox posts now; live posts soon. By Novus Index LLC.

HelpWell

Workado, LLC

HelpWell connects AI assistants to your help desk, knowledge base, live chat support and email marketing automation for SaaS. Triage support tickets, draft help docs and replies, manage contacts, and prepare newsletters

Agent Inbox

Agent Inbox

Give your agent an inbox. Its own address on email, Slack and Telegram. A product of Novu

Advertise