@symbolstar/gmail-mcp

A Node.js/TypeScript MCP (Model Context Protocol) stdio server that lets AI assistants like OpenClaw read your Gmail via the Gmail API.

Features

• OAuth 2.0 authorization with Gmail read-only scope
• list_emails — list inbox emails with optional filters
• get_email — read a single email by message ID
• search_emails — search with Gmail query syntax
• list_labels — list all Gmail labels/folders
• Works with any MCP-compatible client (OpenClaw, Claude Desktop, etc.)

Quick Start

# Step 1: Authorize Gmail access (one-time setup)
npx @symbolstar/gmail-mcp auth

# Step 2: Done — the MCP server starts automatically when called by your client

Setup Guide

Step 1 — Create a Google Cloud Project & Enable Gmail API

1. Open Google Cloud Console
2. Create a new project (or select an existing one)
3. Go to APIs & Services → Library
4. Search for Gmail API and click Enable

Step 2 — Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Under Get started, fill in:
   • App name: e.g. Gmail MCP
   • User support email: your Gmail address
3. Under Audience, select External
4. Under Data Access, add the scope: https://www.googleapis.com/auth/gmail.readonly
5. Under Audience → Test users, add your Gmail address

   ⚠️ This step is required. Without it, you'll get Error 403: access_denied during authorization.

Step 3 — Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name it anything (e.g. gmail-mcp-cli)
5. Click Create, then Download JSON

Step 4 — Place credentials.json

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

The file must be at:

~/.gmail-mcp/credentials.json

Step 5 — Run Authorization

npx @symbolstar/gmail-mcp auth

This will:

• Start a temporary local OAuth callback server
• Open your browser for Google authorization
• Save the token to ~/.gmail-mcp/token.json

If the browser doesn't open automatically, copy the URL printed in the terminal and open it manually.

Integrate with OpenClaw

Add the following to your ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "gmail": {
        "command": "npx",
        "args": ["-y", "@symbolstar/gmail-mcp"]
      }
    }
  }
}

Then restart the gateway:

openclaw gateway restart

Integrate with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@symbolstar/gmail-mcp"]
    }
  }
}

Available Tools

list_emails

List inbox emails.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | maxResults | number | 10 | Max emails to return (up to 50) | | query | string | — | Gmail search query (applied within INBOX) |

get_email

Read a single email by ID.

| Parameter | Type | Description | |-----------|------|-------------| | messageId | string | Gmail message ID |

Returns: sender, recipients, subject, date, labels, plain text body, HTML body, attachment metadata.

search_emails

Search Gmail with full query syntax.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | — | Gmail search query (required) | | maxResults | number | 10 | Max results (up to 50) |

list_labels

List all Gmail labels and folders. No parameters required.

File Locations

| File | Path | |------|------| | OAuth credentials | ~/.gmail-mcp/credentials.json | | OAuth token | ~/.gmail-mcp/token.json |

Troubleshooting

Missing Gmail OAuth credentials

Make sure you downloaded the OAuth client JSON and placed it at ~/.gmail-mcp/credentials.json.

Missing Gmail OAuth token

Run the authorization flow first:

npx @symbolstar/gmail-mcp auth

Error 403: access_denied

Your Gmail account is not added as a Test user. Go to Google Cloud Console → OAuth consent screen → Audience → Test users and add your Gmail address.

invalid_grant

Token expired or revoked. Delete it and re-authorize:

rm ~/.gmail-mcp/token.json
npx @symbolstar/gmail-mcp auth

Requirements

• Node.js 18+
• A Google account with Gmail

License

MIT