Gmail MCP Server
About
A Model Context Protocol (MCP) server for Gmail integration in Claude Desktop with auto authentication support. This server enables AI assistants to manage Gmail through natural language interactions.
Details
- License
- MIT
Explore
- Send emails with subject, content, attachments, and recipients
- Full attachment support - send and receive file attachments
- Download email attachments to local filesystem
- Download full emails to files in json/eml/txt/html formats
- Thread-level operations - get full threads, list inbox threads, batch-expand threads
- Support for HTML emails and multipart messages with both HTML and plain text versions
- Full support for international characters in subject lines and email content
- Read email messages by ID with advanced MIME structure handling
- Enhanced attachment display showing filenames, types, sizes, and download IDs
- Search emails with various criteria (subject, sender, date range)
- Comprehensive label management with ability to create, update, delete and list labels
- List all available Gmail labels (system and user-defined)
- List emails in inbox, sent, or custom labels
- Mark emails as read/unread
- Move emails to different labels/folders
- Delete emails
- Batch operations for efficiently processing multiple emails at once
- Full integration with Gmail API
- Simple OAuth2 authentication flow with auto browser launch
- Support for both Desktop and Web application credentials
- Global credential storage for convenience
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Gmail MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
npx @artymclabin/gmail-mcp auth
git clone https://github.com/ArtyMcLabin/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
npm run build
> Note: The npx @gongrzhe/server-gmail-autoauth-mcp commands found in older docs reference the unmaintained upstream fork. This fork is published as @artymclabin/gmail-mcp.
node dist/index.js auth
b. Local Authentication:
node dist/index.js auth
The authentication process will:
- Look for gcp-oauth.keys.json in the current directory or ~/.gmail-mcp/
- If found in current directory, copy it to ~/.gmail-mcp/
- Open your default browser for Google authentication
- Save credentials as ~/.gmail-mcp/credentials.json
> Note:
> - After successful authentication, credentials are stored globally in ~/.gmail-mcp/ and can be used from any directory
> - Both Desktop app and Web application credentials are supported
> - For Web application credentials, make sure to add http://localhost:3000/oauth2callback to your authorized redirect URIs
Custom callback URL / port: By default the local OAuth server listens on port 3000 at /oauth2callback. If port 3000 is unavailable, or you need a different redirect URI, pass a full callback URL as an argument. The listener automatically binds to the port and path from that URL:
node dist/index.js auth http://localhost:8080/oauth2callback
The URL you pass must exactly match one of the authorized redirect URIs registered in the Google Cloud Console.
3. Configure in Claude Desktop:
{
"mcpServers": {
"gmail": {
"command": "node",
"args": [
"/absolute/path/to/Gmail-MCP-Server/dist/index.js"
]
}
}
}
For cloud server environments (like n8n), you can specify a custom callback URL during authentication:
node dist/index.js auth https://gmail.gongrzhe.com/oauth2callback
1. Configure Reverse Proxy:
- Set up your n8n container to expose a port for authentication
- Configure a reverse proxy to forward traffic from your domain (e.g., gmail.gongrzhe.com) to this port
2. DNS Configuration:
- Add an A record in your DNS settings to resolve your domain to your cloud server's IP address
3. Google Cloud Platform Setup:
- In your Google Cloud Console, add your custom domain callback URL (e.g., https://gmail.gongrzhe.com/oauth2callback) to the authorized redirect URIs list
4. Run Authentication:
node dist/index.js auth https://gmail.gongrzhe.com/oauth2callback
5. Configure in your application:
{
"mcpServers": {
"gmail": {
"command": "node",
"args": [
"/absolute/path/to/Gmail-MCP-Server/dist/index.js"
]
}
}
}
This approach allows authentication flows to work properly in environments where localhost isn't accessible, such as containerized applications or cloud servers.
To use this MCP server with Claude Code, add it to your MCP settings.
First, authenticate with read-only scope:
node dist/index.js auth --scopes=gmail.readonly
Then add to your Claude Code MCP settings (~/.claude/mcp_settings.json or project-level .mcp.json):
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"]
}
}
}
With read-only scopes, only these 4 tools will be available to Claude:
- read_email - Read email content
- search_emails - Search your inbox
- list_email_labels - List available labels
- download_attachment - Download attachments
For full Gmail management capabilities:
node dist/index.js auth --scopes=gmail.modify,gmail.settings.basic
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"]
}
}
}
This enables all 23 tools including sending emails, managing labels, creating filters, reply-all, thread operations, phishing reports, and batch operations.
Some MCP clients dedupe tool entries by their base name across servers, which makes it impossible to run two instances of this server side-by-side (e.g. one for a personal account and one for a shared inbox) - only one instance's tools surface, even though both servers report as connected.
The server accepts an optional --tool-prefix=<value> CLI flag (or GMAIL_MCP_TOOL_PREFIX env var) that is prepended to every tool name at registration. Default is empty (fully backward-compatible).
Example: register two instances with distinct prefixes in Claude Code:
The server provides the following tools that can be used through Claude Desktop:
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"gmail mcp server": {
"Gmail-MCP-Server": {
"command": "npx",
"args": [
"@artymclabin/gmail-mcp",
"auth"
]
}
}
}
}McpServers
{
"Gmail-MCP-Server": {
"command": "npx",
"args": [
"@artymclabin/gmail-mcp",
"auth"
]
}
}Gmail AutoAuth MCP Server (Actively Maintained Fork)
Installation: just tell your Claude to install the MCP from this repo - point it at https://github.com/ArtyMcLabin/Gmail-MCP-Server and let it set up. Prefer manual steps? See Installation & Authentication.
> This is an actively maintained fork of GongRzhe/Gmail-MCP-Server.
>
> The original repository has been unmaintained since August 2025 - 7+ months with zero maintainer activity and 72+ unmerged pull requests. I use this MCP server daily as part of my Claude Code workflow and depend on it working correctly, so I picked it up.
>
> Pull requests are welcome. If you've been sitting on fixes or features with nowhere to submit them, this is the place.
Philosophy
This fork is lean and pragmatic. It's a local stdio MCP server - you run it on your own machine, and your LLM client already has shell + filesystem access. So the threat model is "don't leak credentials to third parties, don't break the Gmail surface" - not "defend a hosted multi-tenant service". I keep dependencies minimal. I use this daily in my own Claude Code workflow - if I wouldn't run it or maintain it myself, it doesn't go in.
There's a downstream fork that took this in the maximalist direction. I'm not affiliated with its maintainer and I don't track its security or features - use it at your own risk: klodr/gmail-mcp. If that's the philosophy you want, go check it out. PRs welcome here as always.
What this fork adds
- Fixed reply threading - auto-resolves In-Reply-To and References headers so email replies land in the correct thread instead of creating orphaned messages (upstream PR #91, still pending)
- Send-as alias support - optional from parameter for multi-identity email management (send from any configured Gmail alias)
- Reply-all tool - reply_all automatically fetches the original email, builds To/CC recipient lists (excluding yourself), and sets proper threading headers (PR #3 by @MaxGhenis)
- Fixed list_filters - was returning empty array due to wrong response property name (PR #4 by @nicholas-anthony-ai)
- Custom OAuth2 scoping - --scopes flag to request only the permissions you need, with automatic tool filtering (PR #6 by @tansanDOTeth)
- CI/CD hardening - fixed shell injection vector in GitHub Actions workflow, added least-privilege permissions scope (PR #9 by @JF10R)
- Security hardening - fixed path traversal in attachment download, restricted OAuth credential file permissions (PR #10 by @JF10R)
- Dependency security - upgraded MCP SDK to v1.27.1 (3 CVE fixes), upgraded nodemailer (DoS + routing fix), moved dev-only packages out of production deps (PR #11 by @JF10R)
- Thread-level tools - get_thread, list_inbox_threads, get_inbox_with_threads, modify_thread for efficient thread-based email operations in a single call
- CC/BCC visibility - read_email now shows CC and BCC headers when present (PR #21 by @panghy)
- Phishing report tools - report_phishing and batch_report_phishing for marking messages as spam via the Gmail API (PR #24 by @ShivamB25)
- Draft lifecycle tools - send_draft, delete_draft, update_draft close the orphan-draft gap: send_draft atomically sends an existing draft and removes it from Drafts (no ghost copy); update_draft mutates a draft in place preserving its ID (no draft pile-up across iteration loops); delete_draft discards an abandoned draft (PR #30 by @thisisambros)
- Tool annotations - MCP spec annotations (readOnlyHint, destructiveHint, idempotentHint) on all tools for safer LLM tool execution (PR #14 by @bryankthompson)
- Download email tool - download_email saves emails to disk in json/eml/txt/html formats without consuming LLM context (PR #13 by @icanhasjonas)
All features are production-tested in daily use.
---
A Model Context Protocol (MCP) server for Gmail integration in Claude Desktop with auto authentication support. This server enables AI assistants to manage Gmail through natural language interactions.
Features
- Send emails with subject, content, attachments, and recipients
- Full attachment support - send and receive file attachments
- Download email attachments to local filesystem
- Download full emails to files in json/eml/txt/html formats
- Thread-level operations - get full threads, list inbox threads, batch-expand threads
- Support for HTML emails and multipart messages with both HTML and plain text versions
- Full support for international characters in subject lines and email content
- Read email messages by ID with advanced MIME structure handling
- Enhanced attachment display showing filenames, types, sizes, and download IDs
- Search emails with various criteria (subject, sender, date range)
- Comprehensive label management with ability to create, update, delete and list labels
- List all available Gmail labels (system and user-defined)
- List emails in inbox, sent, or custom labels
- Mark emails as read/unread
- Move emails to different labels/folders
- Delete emails
- Batch operations for efficiently processing multiple emails at once
- Full integration with Gmail API
- Simple OAuth2 authentication flow with auto browser launch
- Support for both Desktop and Web application credentials
- Global credential storage for convenience
Installation & Authentication
Installing from npm (recommended)
npx @artymclabin/gmail-mcp auth
Installing from source
git clone https://github.com/ArtyMcLabin/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
npm run build
> Note: The npx @gongrzhe/server-gmail-autoauth-mcp commands found in older docs reference the unmaintained upstream fork. This fork is published as @artymclabin/gmail-mcp.
Setting up Google Cloud credentials
1. Create a Google Cloud Project and obtain credentials:
a. Create a Google Cloud Project:
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API for your project
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
