Provides comprehensive Gmail inbox management with 26 tools for reading, searching, organizing emails, managing labels, creating drafts, and supporting multiple connected Gmail accounts with thread-aware operations.
Click on "Install 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 Serversearch for emails from my boss this week"
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
An MCP (Model Context Protocol) server that exposes Gmail inbox tools via Streamable HTTP transport. Connect your Gmail accounts to Claude Code and other MCP-compatible clients to search, read, organize, and compose emails.
Features
Multi-account support - Connect multiple Gmail accounts and switch between them
Full Gmail access - Search messages, read threads, manage labels, archive, star, and compose drafts
Secure token storage - Refresh tokens encrypted with AES-256-GCM in SQLite
Two-layer OAuth - MCP-level JWT authentication plus Google OAuth for Gmail
Docker ready - Run with Docker Compose for easy deployment
Quick Start
1. Clone and install
2. Configure Google OAuth
Go to Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API
Create OAuth 2.0 credentials (Web application)
Set authorized redirect URI to
http://localhost:3000/oauth/callbackCopy the Client ID and Client Secret
3. Set up environment
4. Build and run
The server runs on http://localhost:3000.
5. Connect to Claude Code
This installs the MCP server connection and Gmail skills.
Claude Code Integration
Setup
After the server is running, install the Claude Code integration:
This installs:
MCP server connection to
~/.claude.json4 subagents to
~/.claude/agents/(auto-triggered by context)14 skills to
~/.claude/skills/(explicit/command)
Subagents (Auto-Triggered)
Subagents run automatically when Claude detects matching context. They operate in isolated context and return concise summaries.
Subagent | Triggers on... |
| "prioritize my inbox", "what needs attention", "urgent emails" |
| "clean up inbox", "what can I archive", "declutter" |
| "analyze my inbox", "email patterns", "inbox overview" |
| "find emails about X", "summarize emails from Y" |
Examples:
Skills (Explicit Commands)
Skills run when you explicitly type /command. They run in your conversation context.
Command | Description |
| Quick inbox status |
| List unread messages |
| View starred messages |
| View all labels |
| View pending drafts |
| Search with Gmail query syntax |
| View a conversation thread |
| Draft new emails |
| Summarize email threads |
| Prioritize unread emails |
| Archive and organize inbox |
| Comprehensive inbox overview |
| Connect Gmail account |
| View connected accounts |
Management
Configuration
Create a .env file based on .env.example:
Variable | Description | Required |
| Server port (default: 3000) | No |
| Public URL for OAuth callbacks | Yes |
| Google OAuth client ID | Yes |
| Google OAuth client secret | Yes |
| OAuth callback URL | Yes |
| 32-byte base64 key for token encryption | Yes |
| Secret for MCP JWT tokens | Yes |
| SQLite database path (default: | No |
| Comma-separated CORS origins | No |
Available Tools
Authorization & Status
Tool | Description |
| Check connection status and list connected accounts |
| Initiate OAuth flow to connect a Gmail account |
Account Management
Tool | Description |
| List all connected Gmail accounts |
| Set the default account for operations |
| Disconnect a Gmail account |
Reading Email
Tool | Description |
| Search using Gmail query syntax |
| Run multiple searches in parallel |
| Get a single message by ID |
| List conversation threads |
| Get all messages in a thread |
| Get attachment info |
Labels
Tool | Description |
| List all labels with counts |
| Get details about a specific label |
| Create a custom label |
| Add labels to messages/threads |
| Remove labels from messages/threads |
Modifications
Tool | Description |
| Archive messages/threads |
| Move back to inbox |
| Mark as read |
| Mark as unread |
| Add star |
| Remove star |
Drafts
Tool | Description |
| Create a new draft |
| List all drafts |
| Get draft content |
| Update an existing draft |
| Delete a draft |
OAuth Scopes
Request only the scopes you need:
Scope | Capabilities |
| Search, read messages and threads |
| Manage labels, archive, star, mark read/unread |
| All of the above |
| Create and manage drafts |
Multi-Account Support
Connect multiple Gmail accounts per user:
Docker Deployment
The SQLite database persists in ./data/.
Development
Architecture
src/index.ts- Entry pointsrc/http/server.ts- Fastify server with/mcp,/oauth/*,/healthzendpointssrc/mcp/server.ts- MCP server with 26 registered toolssrc/gmail/client.ts- Gmail API wrapper with token refreshsrc/auth/- MCP JWT auth and Google OAuth flowssrc/store/sqlite.ts- SQLite token store with AES-256-GCM encryption
License
MIT