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_emails

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