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

git clone https://github.com/yourusername/gmail-mcp.git
cd gmail-mcp
npm install

2. Configure Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API
4. Create OAuth 2.0 credentials (Web application)
5. Set authorized redirect URI to http://localhost:3000/oauth/callback
6. Copy the Client ID and Client Secret

3. Set up environment

# Generate secure secrets
npm run setup:secrets

# Edit .env with your Google OAuth credentials
# Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

4. Build and run

npm run build
npm run start

The server runs on http://localhost:3000.

5. Connect to Claude Code

npm run claude:setup

This installs the MCP server connection and Gmail skills.

Claude Code Integration

Setup

After the server is running, install the Claude Code integration:

npm run claude:setup

This installs:

• MCP server connection to ~/.claude.json
• 4 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...
gmail-triage	"prioritize my inbox", "what needs attention", "urgent emails"
gmail-cleanup	"clean up inbox", "what can I archive", "declutter"
gmail-explore	"analyze my inbox", "email patterns", "inbox overview"
gmail-research	"find emails about X", "summarize emails from Y"

Examples:

> What needs my attention in email?
→ Auto-triggers gmail-triage subagent

> Find all emails about the project proposal
→ Auto-triggers gmail-research subagent

Skills (Explicit Commands)

Skills run when you explicitly type /command. They run in your conversation context.

Command	Description
/gmail-inbox	Quick inbox status
/gmail-unread	List unread messages
/gmail-starred	View starred messages
/gmail-labels	View all labels
/gmail-drafts	View pending drafts
/gmail-search	Search with Gmail query syntax
/gmail-thread	View a conversation thread
/gmail-compose	Draft new emails
/gmail-summarize	Summarize email threads
/gmail-triage	Prioritize unread emails
/gmail-cleanup	Archive and organize inbox
/gmail-explore	Comprehensive inbox overview
/gmail-connect	Connect Gmail account
/gmail-accounts	View connected accounts

Management

npm run claude:status     # Check what's installed
npm run claude:uninstall  # Remove integration

Configuration

Create a .env file based on .env.example:

Variable	Description	Required
PORT	Server port (default: 3000)	No
BASE_URL	Public URL for OAuth callbacks	Yes
GOOGLE_CLIENT_ID	Google OAuth client ID	Yes
GOOGLE_CLIENT_SECRET	Google OAuth client secret	Yes
OAUTH_REDIRECT_URI	OAuth callback URL	Yes
TOKEN_ENCRYPTION_KEY	32-byte base64 key for token encryption	Yes
JWT_SECRET	Secret for MCP JWT tokens	Yes
DB_URL	SQLite database path (default: ./data/gmail-mcp.db)	No
ALLOWED_ORIGINS	Comma-separated CORS origins	No

Available Tools

Authorization & Status

Tool	Description
gmail.status	Check connection status and list connected accounts
gmail.authorize	Initiate OAuth flow to connect a Gmail account

Account Management

Tool	Description
gmail.listAccounts	List all connected Gmail accounts
gmail.setDefaultAccount	Set the default account for operations
gmail.removeAccount	Disconnect a Gmail account

Reading Email

Tool	Description
gmail.searchMessages	Search using Gmail query syntax
gmail.batchSearchMessages	Run multiple searches in parallel
gmail.getMessage	Get a single message by ID
gmail.listThreads	List conversation threads
gmail.getThread	Get all messages in a thread
gmail.getAttachmentMetadata	Get attachment info

Labels

Tool	Description
gmail.listLabels	List all labels with counts
gmail.getLabelInfo	Get details about a specific label
gmail.createLabel	Create a custom label
gmail.addLabels	Add labels to messages/threads
gmail.removeLabels	Remove labels from messages/threads

Modifications

Tool	Description
gmail.archiveMessages	Archive messages/threads
gmail.unarchiveMessages	Move back to inbox
gmail.markAsRead	Mark as read
gmail.markAsUnread	Mark as unread
gmail.starMessages	Add star
gmail.unstarMessages	Remove star

Drafts

Tool	Description
gmail.createDraft	Create a new draft
gmail.listDrafts	List all drafts
gmail.getDraft	Get draft content
gmail.updateDraft	Update an existing draft
gmail.deleteDraft	Delete a draft

OAuth Scopes

Request only the scopes you need:

Scope	Capabilities
gmail.readonly	Search, read messages and threads
gmail.labels	Manage labels, archive, star, mark read/unread
gmail.modify	All of the above
gmail.compose	Create and manage drafts

Multi-Account Support

Connect multiple Gmail accounts per user:

// First account becomes the default
gmail.authorize → connects work@company.com (default)
gmail.authorize → connects personal@gmail.com

// Use specific account
gmail.searchMessages(query: "...", email: "personal@gmail.com")

// Or change the default
gmail.setDefaultAccount(email: "personal@gmail.com")

Docker Deployment

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

The SQLite database persists in ./data/.

Development

# Dev mode with hot reload
npm run dev

# Run tests
npm run test

# Type check
npm run typecheck

# Lint
npm run lint

Architecture

MCP Client → Fastify HTTP (/mcp) → MCP Server → Gmail Client → Google APIs
                    ↓
            Token Store (SQLite) ← encrypted credentials

• src/index.ts - Entry point
• src/http/server.ts - Fastify server with /mcp, /oauth/*, /healthz endpoints
• src/mcp/server.ts - MCP server with 26 registered tools
• src/gmail/client.ts - Gmail API wrapper with token refresh
• src/auth/ - MCP JWT auth and Google OAuth flows
• src/store/sqlite.ts - SQLite token store with AES-256-GCM encryption

License

MIT