Skip to main content
Glama
gmail-mcp

gmail-mcp

by SymbolStar

Gmail MCP Server

Gmail MCP Server is a Node.js/TypeScript-based MCP stdio server that allows OpenClaw to read Gmail emails via the Model Context Protocol.

Features

  • Uses Gmail API OAuth 2.0 authorization with read-only scope: https://www.googleapis.com/auth/gmail.readonly

  • list_emails: Lists inbox emails, supporting maxResults and Gmail query filtering

  • get_email: Reads details of a single email via messageId

  • search_emails: Searches for emails using Gmail search syntax

  • list_labels: Lists all Gmail labels/folders

  • Supports MCP stdio transport for OpenClaw integration

Related MCP server: gmail-mcp

Requirements

  • Node.js 18 or higher

  • npm

  • A Google account with access to the Gmail API

Installation

npm install
npm run build

Create OAuth Credentials in Google Cloud Console

  1. Open the Google Cloud Console.

  2. Create or select a project.

  3. Go to APIs & Services -> Library, search for and enable Gmail API.

  4. Go to APIs & Services -> OAuth consent screen.

  5. Select the user type. For personal use, usually select External.

  6. Fill in the application name, user support email, and developer contact email.

  7. In the Scopes step, add the Gmail read-only permission: https://www.googleapis.com/auth/gmail.readonly.

  8. If the app is in Testing status, add your Gmail account to Test users.

  9. Go to APIs & Services -> Credentials.

  10. Click Create Credentials -> OAuth client ID.

  11. Select Desktop app as the Application type.

  12. Download the JSON file after creation.

Place credentials.json

Create the configuration directory and save the downloaded OAuth JSON as:

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

The final path must be:

~/.gmail-mcp/credentials.json

Run Authorization Flow

npm run auth

The script will:

  • Start a temporary local OAuth callback service

  • Open the browser for Google authorization

  • Save the token to ~/.gmail-mcp/token.json after authorization is complete

If the browser does not open automatically, the terminal will print the authorization URL; copy it to your browser manually.

Start MCP Server

npm run start

start uses stdio transport and is typically started by OpenClaw as an MCP server subprocess; it does not need to be run manually for long periods.

OpenClaw MCP Configuration Example

Point the command to the built entry point of this project:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
    }
  }
}

You can also start it using npm within the project directory:

{
  "mcpServers": {
    "gmail": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/Volumes/DevDisk/symbol/gmailMCP"
    }
  }
}

Tools Parameter Description

list_emails

List inbox emails.

{
  "maxResults": 10,
  "query": "from:example@gmail.com newer_than:7d"
}
  • maxResults: Optional, default 10, maximum 50

  • query: Optional, Gmail search syntax, restricted to INBOX queries

get_email

Read details of a single email.

{
  "messageId": "18f..."
}

Returned fields include sender, recipient, subject, date, labels, body text, HTML body, and attachment metadata.

Search Gmail emails.

{
  "query": "subject:invoice has:attachment newer_than:30d",
  "maxResults": 10
}
  • query: Required, supports Gmail search syntax

  • maxResults: Optional, default 10, maximum 50

list_labels

List all labels/folders.

{}

File Locations

  • OAuth credentials: ~/.gmail-mcp/credentials.json

  • OAuth token: ~/.gmail-mcp/token.json

  • MCP server entry point: dist/src/index.js

FAQ

Missing Gmail OAuth credentials

Confirm that you have downloaded the Google OAuth client JSON and saved it to:

~/.gmail-mcp/credentials.json

Missing Gmail OAuth token

Run the following first:

npm run auth

access_denied or app not verified

If the OAuth consent screen is still in Testing status, you need to add the current Gmail account to Test users.

invalid_grant

Delete the old token and re-authorize:

rm ~/.gmail-mcp/token.json
npm run auth

Available Tools

4 tools
get_emailA

Read one Gmail message by messageId.

Inputs: messageId (required).

list_emailsB

List Gmail inbox messages. Supports maxResults and Gmail query filters.

Inputs: maxResults, query.

list_labelsA

List all Gmail labels and folders.

Inputs: no named parameters.

search_emailsA

Search Gmail messages with Gmail search syntax.

Inputs: query (required), maxResults.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct operation: reading a single email by ID, listing inbox messages, searching with Gmail syntax, and listing labels. There is no overlap in functionality.

    Naming Consistency5/5

    All tool names follow the consistent verb_noun pattern in snake_case: get_email, list_emails, list_labels, search_emails.

    Tool Count4/5

    With 4 tools, the set is concise and scoped to basic read and list operations. While it covers common use cases, it could be expanded with write operations, but the count is reasonable for a focused subset.

    Completeness2/5

    The tool surface lacks write operations such as sending, deleting, or modifying emails and labels. Users cannot perform actions beyond reading and listing, which is a significant gap for comprehensive Gmail management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive Gmail integration with LLM processing capabilities, allowing users to read, search, filter emails and handle attachments through the Model Context Protocol.
      25 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables full management of Gmail accounts, including messages, threads, labels, and drafts. It leverages the Gmail API to allow searching, sending, and organizing emails via secure OAuth2 authentication.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides access to Gmail functionality through the Model Context Protocol, allowing LLMs like Claude to interact with your email.
      2
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to manage Gmail through natural language, including search, read, send, label, and draft operations via the Model Context Protocol.
      -