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
| Tool | Description |
|---|---|
list_emails |
List emails from inbox or any label with optional query filter |
read_email |
Read full email content (headers + decoded body) |
search_emails |
Search using Gmail query syntax |
list_attachments_with_safety |
List message attachments with policy-based safety checks |
validate_attachment |
Validate one attachment against local file safety policy |
download_attachment_safe |
Download attachment only if it passes safety policy checks |
redact_text_local |
Redact sensitive text through local privacy pipeline |
read_email_with_privacy |
Read one email with privacy-redacted subject/snippet/body |
send_email |
Send plain-text or HTML emails |
create_draft |
Create email drafts without sending |
reply_to_email |
Reply to an email thread (preserves threading headers) |
delete_email |
Trash or permanently delete an email |
mark_as_read |
Mark email as read |
mark_as_unread |
Mark email as unread |
set_labels |
Add/remove labels on an email |
get_labels |
List all Gmail labels with message counts |
get_profile |
Get authenticated user profile info |
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:```bash
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.
---
## 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)```bash
# 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)```bash
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)```bash
# 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```bash
docker build -t gmail-mcp-server .
### Run the MCP server (with env vars)```bash
# Copy .env.example → .env and fill in credentials
cp .env.example .env
docker compose up
Or pass credentials inline:```bash
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```bash
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```bash
docker run -i \
-v ./credentials:/app/credentials:ro \
gmail-mcp-server
---
## Environment Variables
| Variable | Required | Description |
|---|---|---|
| `GMAIL_CLIENT_ID` | Yes* | Google OAuth2 Client ID |
| `GMAIL_CLIENT_SECRET` | Yes* | Google OAuth2 Client Secret |
| `GMAIL_REFRESH_TOKEN` | Yes* | Long-lived refresh token (from setup wizard) |
| `GMAIL_REDIRECT_URI` | No | Override redirect URI (default: `http://localhost:3000/oauth/callback`) |
| `PORT` | No | Web UI setup server port (default: `3000`) |
\* 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:```json
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"]
}
}
}
Or use Docker:```json
{
"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 commitcredentials.jsonortoken.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.1only (not publicly accessible) - The runtime Docker container runs as a non-root user (
mcp)
Troubleshooting
| Problem | Solution |
|---|---|
No Gmail credentials found |
Run npm run setup:cli or npm run setup:ui |
No Gmail token found |
Re-run the setup wizard to re-authorize |
invalid_client from Google |
Check that Client ID and Secret are correct |
redirect_uri_mismatch |
Ensure the redirect URI is added in Google Cloud Console exactly as shown in the wizard |
Port 3333 in use |
Kill the process using port 3333, or temporarily change CLI_PORT in src/setup/cli.ts |
Token expired / invalid_grant |
Re-run the setup wizard to get a fresh refresh token |
Docker: credentials not found |
Mount ./credentials:/app/credentials or set env vars |
