Gmail MCP Server

A comprehensive Model Context Protocol (MCP) server for Gmail, with 17 tools, an interactive CLI setup wizard, a browser-based Web UI wizard, and full Docker support.

Features

Attachment safety policy defaults are defined in src/config/attachment-policy.json. Privacy policy defaults are defined in src/config/privacy-policy.json.

Optional local privacy stack (vLLM + privacy orchestrator) can be started with Docker profiles:

docker compose --profile privacy up --build

The privacy profile also enables optional persistent services:

• Redis (redis:6379) — token store for session-aware PII re-identification (future feature)

• SQLite (audit.db) — audit log of all PII detections and redactions for compliance

See ARCHITECTURE.md for database design details.

Related MCP server: gmail-mcp

Prerequisites

• Node.js 20+ (for local setup)

• Docker (for containerised setup)

• A Google Cloud project with Gmail API enabled and an OAuth2 Client ID (Desktop app type)

Google Cloud Setup (one-time)

1. Go to https://console.cloud.google.com/

2. Create or select a project

3. APIs & Services → Library → search "Gmail API" → Enable

4. APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID

   • Application type: Desktop app

   • Add Authorized redirect URIs:

     • http://localhost:3333/oauth/callback ← for CLI wizard

     • http://localhost:3000/oauth/callback ← for Web UI wizard

5. Note your Client ID and Client Secret (or download credentials.json)

Quick Start

Option A — CLI Wizard (recommended for developers)

# 1. Install dependencies and build
npm install
npm run build

# 2. Run the interactive CLI setup wizard
npm run setup:cli

# 3. Start the MCP server
npm start

The CLI wizard will:

• Guide you through credential input (file / paste JSON / manual entry)

• Let you choose Gmail permission scopes

• Open your browser for Google sign-in

• Automatically capture the OAuth callback and save tokens

• Validate the connection and print your email + next steps

Option B — Web UI Wizard (browser-based)

# 1. Install dependencies and build
npm install
npm run build

# 2. Start the setup wizard UI
npm run setup:ui

# 3. Open http://localhost:3000 in your browser
#    Complete the 4-step wizard, then start the server:
npm start

The Web UI provides a guided 4-step flow:

1. Enter OAuth2 credentials

2. Select permission scopes

3. Click Authorize Gmail Access → completes Google sign-in flow

4. Success page with connection stats and next steps

Option C — Manual .env (CI / Docker production)

# Copy and fill in the template
cp .env.example .env
# Edit .env: set GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN

npm install
npm run build
npm start

Docker

Build the image

docker build -t gmail-mcp-server .

Run the MCP server (with env vars)

# Copy .env.example → .env and fill in credentials
cp .env.example .env

docker compose up

Or pass credentials inline:

docker run -i \
  -e GMAIL_CLIENT_ID=your-client-id \
  -e GMAIL_CLIENT_SECRET=your-secret \
  -e GMAIL_REFRESH_TOKEN=your-refresh-token \
  gmail-mcp-server

Run the Web UI Setup Wizard via Docker

docker compose -f docker-compose.setup.yml up

Then open http://localhost:3000 — credentials are written back to ./credentials/ on the host via volume mount.

Mount credentials files instead of env vars

docker run -i \
  -v ./credentials:/app/credentials:ro \
  gmail-mcp-server

Environment Variables

* Required when using env vars. Alternatively, use credentials/credentials.json + credentials/token.json (written by the setup wizards).

Add to MCP Client (e.g. Claude Desktop)

Edit your MCP client config:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"]
    }
  }
}

Or use Docker:

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GMAIL_CLIENT_ID=...",
        "-e", "GMAIL_CLIENT_SECRET=...",
        "-e", "GMAIL_REFRESH_TOKEN=...",
        "gmail-mcp-server"
      ]
    }
  }
}

Project Structure

├── src/
│   ├── index.ts                  # MCP server entry point
│   ├── gmail/
│   │   ├── auth.ts               # OAuth2 credential + token management
│   │   └── client.ts             # Gmail API client factory (singleton)
│   ├── tools/
│   │   ├── emails.ts             # list_emails, read_email, search_emails
│   │   ├── compose.ts            # send_email, create_draft, reply_to_email
│   │   ├── manage.ts             # delete_email, mark_as_read/unread, set_labels
│   │   └── meta.ts               # get_labels, get_profile
│   └── setup/
│       ├── oauth.ts              # Shared OAuth2 URL generation + token exchange
│       ├── cli.ts                # Interactive CLI setup wizard
│       └── ui-server.ts          # Express Web UI setup server
├── public/
│   └── setup/
│       └── index.html            # 4-step Web UI wizard (vanilla HTML/CSS/JS)
├── credentials/                  # Runtime secrets — gitignored
│   └── .gitkeep
├── Dockerfile                    # Multi-stage build (build + runtime)
├── docker-compose.yml            # MCP server runtime
├── docker-compose.setup.yml      # Web UI setup wizard runtime
├── .env.example                  # Environment variable template
└── tsconfig.json

Security Notes

• credentials/ is gitignored — never commit credentials.json or token.json

• Credentials are not baked into the Docker image — always injected via env vars or volume mounts

• The Web UI server and CLI callback server bind to 127.0.0.1 only (not publicly accessible)

• The runtime Docker container runs as a non-root user (mcp)

Troubleshooting