gmail-mcp-server
Allows reading, searching, sending, and managing emails in Gmail, including attachments, labels, drafts, and privacy redaction.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gmail-mcp-server show me my latest emails"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 from inbox or any label with optional query filter |
| Read full email content (headers + decoded body) |
| Search using Gmail query syntax |
| List message attachments with policy-based safety checks |
| Validate one attachment against local file safety policy |
| Download attachment only if it passes safety policy checks |
| Redact sensitive text through local privacy pipeline |
| Read one email with privacy-redacted subject/snippet/body |
| Send plain-text or HTML emails |
| Create email drafts without sending |
| Reply to an email thread (preserves threading headers) |
| Trash or permanently delete an email |
| Mark email as read |
| Mark email as unread |
| Add/remove labels on an email |
| List all Gmail labels with message counts |
| 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:
docker compose --profile privacy up --buildThe 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 Server
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)
Create or select a project
APIs & Services → Library → search "Gmail API" → Enable
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 wizardhttp://localhost:3000/oauth/callback← for Web UI wizard
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 startThe 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 startThe Web UI provides a guided 4-step flow:
Enter OAuth2 credentials
Select permission scopes
Click Authorize Gmail Access → completes Google sign-in flow
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 startDocker
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 upOr 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-serverRun the Web UI Setup Wizard via Docker
docker compose -f docker-compose.setup.yml upThen 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-serverEnvironment Variables
Variable | Required | Description |
| Yes* | Google OAuth2 Client ID |
| Yes* | Google OAuth2 Client Secret |
| Yes* | Long-lived refresh token (from setup wizard) |
| No | Override redirect URI (default: |
| No | Web UI setup server port (default: |
* 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.jsonSecurity Notes
credentials/is gitignored — never commitcredentials.jsonortoken.jsonCredentials 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 |
| Run |
| Re-run the setup wizard to re-authorize |
| Check that Client ID and Secret are correct |
| Ensure the redirect URI is added in Google Cloud Console exactly as shown in the wizard |
| Kill the process using port 3333, or temporarily change |
Token expired / | Re-run the setup wizard to get a fresh refresh token |
Docker: | Mount |
Available Tools
18 toolscreate_draftA
Create a draft email in Gmail without sending it.
Inputs: to (required), body (required), subject (required), cc, +3 more.
delete_emailA
Move an email to Trash. Pass permanent: true to permanently delete (irreversible).
Inputs: messageId (required), permanent.
download_attachmentB
Download a specific attachment from a Gmail message. Returns the base64-encoded attachment data and its MIME type.
Inputs: messageId (required), attachmentId (required).
download_attachment_safeA
Safely download one validated attachment. Blocks risky files and enforces policy checks before returning data.
Inputs: messageId (required), attachmentId (required).
get_labelsA
List all Gmail labels (system labels like INBOX, SENT and user-created labels). Returns label IDs, names, and message counts.
Inputs: no named parameters.
get_profileA
Get the authenticated Gmail user profile: email address, total message count, and thread count. Useful to verify the connection.
Inputs: no named parameters.
list_attachments_with_safetyA
List attachments for a message and provide policy-based safety assessment for each file.
Inputs: messageId (required).
list_emailsA
List emails from Gmail. Filter by labels and/or a search query. Returns sender, subject, date, and snippet for each message.
Inputs: query, labelIds, maxResults.
mark_as_readA
Mark an email as read by removing the UNREAD label.
Inputs: messageId (required).
mark_as_unreadB
Mark an email as unread by adding the UNREAD label.
Inputs: messageId (required).
read_emailB
Read the full content of a specific email by its message ID, including headers and decoded body.
Inputs: messageId (required).
read_email_with_privacyA
Read one email and return only privacy-redacted subject/snippet/body fields using the local privacy pipeline.
Inputs: messageId (required).
redact_text_localB
Redact sensitive content from provided text using local privacy pipeline (orchestrator with deterministic fallback).
Inputs: text (required), contentType.
reply_to_emailA
Reply to an existing email thread. Automatically sets Reply-To headers and preserves the thread.
Inputs: body (required), messageId (required), isHtml, attachments.
search_emailsA
Search Gmail using the standard Gmail search syntax. Returns matching emails with sender, subject, date, and snippet.
Inputs: query (required), maxResults.
send_emailC
Send an email via the authenticated Gmail account.
Inputs: to (required), body (required), subject (required), cc, +3 more.
set_labelsA
Add and/or remove labels on an email. Use get_labels to obtain valid label IDs.
Inputs: messageId (required), addLabelIds, removeLabelIds.
validate_attachmentA
Validate one attachment against local safety policy (size, MIME type, extension, filename).
Inputs: messageId (required), attachmentId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Multiple tools have overlapping purposes: list_emails and search_emails both return message lists with similar fields, read_email and read_email_with_privacy both read a single email, and download_attachment/download_attachment_safe/validate_attachment all handle attachment retrieval with safety. The descriptions help distinguish them, but the boundaries are still unclear and could cause misselection.
Most tools follow a consistent verb_noun snake_case pattern (e.g., read_email, list_emails, send_email, get_profile). However, a few tools have irregular modifiers like '_with_safety', '_safe', '_local', and '_with_privacy', which breaks the uniformity slightly but does not create chaos.
18 tools falls in the heavy range and feels slightly bloated due to redundancy. For instance, list_emails and search_emails overlap, and the attachment safety pipeline has three distinct tools that could be consolidated. Each tool has a purpose, but the count could be trimmed without losing capability.
Core Gmail workflows (read, search, send, reply, delete, labels) are covered, but there are significant gaps: create_draft has no way to send or update drafts, and get_labels exists but there are no tools to create or delete labels. This leaves workflows with dead ends, such as creating a draft that cannot be sent via the same server.
Maintenance
Related MCP Connectors
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that integrates with Gmail to enable sending, reading, and managing emails through tools like send-email, trash-email, get-unread-emails, and read-email.73GPL 3.0
- FlicenseNot gradedqualityDmaintenanceA comprehensive MCP server providing 24 tools for full Gmail management, including email operations, label organization, and batch filtering. It features multi-account support and secure OAuth authentication for interacting with mailboxes via natural language.-
- FlicenseBqualityDmaintenanceA Gmail MCP server providing 19 tools for email operations, label and filter management, and attachment handling via the Gmail API.19-
- AlicenseNot gradedqualityCmaintenanceMCP server for Gmail that enables searching, reading, archiving, and managing email from any MCP client.6 npm1MIT