Headless Gmail MCP Server

What does “Headless Gmail” MCP Server do?

The Headless Gmail MCP Server is a Model Context Protocol (MCP) server that enables seamless interaction with Gmail accounts for sending and retrieving emails, all without the need for local credential or token setup. Designed for headless and remote operation, it allows clients to complete OAuth flows independently and pass credentials securely as context, making it possible to run in fully containerized or cloud environments without local file access or browser interaction. This server is ideal for workflows that need focused, reliable Gmail access—such as marketing automation or notification systems—by exposing standardized tools through the MCP interface for email management and integration into AI-powered development pipelines.

List of Prompts

No specific prompt templates are mentioned in the repository.

List of Resources

No explicit MCP resources are described in the available documentation or code.

List of Tools

• Get recent emails
  Retrieves the most recent emails from a Gmail account, returning the first 1,000 characters of the email body.
• Get full email body
  Fetches the full content of an email in 1,000-character chunks using an offset parameter, allowing for large email retrieval.
• Send email
  Sends emails through the connected Gmail account.
• Refresh access token
  Handles token refreshes independently, ensuring ongoing secure access.

Use Cases of this MCP Server

• Automated Email Notifications
  Integrate with AI agents or automation platforms to send real-time email alerts or notifications without manual intervention.
• Gmail Inbox Monitoring
  Fetch and process the latest emails to automate responses, triage, or extract information for downstream workflows.
• Marketing Campaign Automation
  Send personalized marketing emails programmatically, leveraging MCP for scalable, credential-separated campaign execution.
• Seamless API Integration
  Embed Gmail operations into developer environments or other MCP-aware platforms without exposing or managing local credentials.
• Remote/Cloud Email Management
  Manage Gmail accounts within Dockerized or remote setups, enabling secure, headless operation without local dependencies.

How to set it up

Windsurf

1. Ensure you have Node.js and Windsurf installed.
2. Open your configuration file (e.g., windsurf.json).
3. Add the Headless Gmail MCP Server to the mcpServers section:

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

4. Save changes and restart Windsurf.
5. Verify the server is running from the Windsurf dashboard.

Securing API Keys
Use environment variables to pass credentials securely:

{
  "mcpServers": {
    "headless-gmail": {
      "command": "npx",
      "args": ["@baryhuang/mcp-headless-gmail@latest"],
      "env": {
        "GMAIL_CLIENT_ID": "...",
        "GMAIL_CLIENT_SECRET": "...",
        "GMAIL_ACCESS_TOKEN": "...",
        "GMAIL_REFRESH_TOKEN": "..."
      }
    }
  }
}

Claude

1. Install Claude and ensure Node.js is available.
2. Edit the configuration file (e.g., claude.json).
3. Add the server:

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

4. Save and restart Claude.
5. Check for server status within Claude’s interface.

Securing API Keys
Use the env key as above to securely inject credentials.

Cursor

1. Ensure Cursor is installed and up-to-date.
2. Open Cursor’s settings or configuration file.
3. Insert the MCP server entry:

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

4. Save and restart Cursor.
5. Confirm the MCP server is detected.

Securing API Keys
Configure credentials using the env section as shown previously.

Cline

1. Install Cline and dependencies.
2. Open the Cline configuration file.
3. Add the MCP server:

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

4. Save changes, then restart Cline.
5. Ensure server connectivity via Cline’s tools.

Securing API Keys
Pass API credentials using environment variables in the configuration as in previous examples.

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{
  "headless-gmail": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change “headless-gmail” to whatever the actual name of your MCP server is (e.g., “github-mcp”, “weather-api”, etc.) and replace the URL with your own MCP server URL.

Overview

Our opinion

Based on the available information, the Headless Gmail MCP Server is highly focused and easy to integrate, with clear instructions for most platforms and robust Docker/headless support. However, it lacks explicit prompt templates and resource definitions, which may limit some advanced MCP features. Its strengths lie in simplicity, security, and real-world utility for email-focused automation. Overall, it’s practical and reliable for its intended use, but not as feature-complete as some other MCP servers.

MCP Score