Gmail MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with Gmail through secure OAuth 2.0 authentication. Send emails, search messages, read emails, and manage multiple Gmail accounts directly from Claude Desktop.

Features

• Secure OAuth 2.0 Authentication - No passwords stored, tokens auto-refresh
• Multiple Account Support - Manage multiple Gmail accounts simultaneously
• Email Operations - Send, search, and read emails with full Gmail API support
• Advanced Search - Use Gmail's powerful search operators
• Real-time Integration - Works seamlessly with Claude Desktop

Quick Start

1. Setup Google Cloud Console:

   • Create a project and enable Gmail API
   • Create OAuth 2.0 credentials for desktop application
   • Download credentials as credentials.json

2. Install and Build:

   npm install
   npm run build
   

3. Configure Claude Desktop:

   • Place credentials.json in Claude Desktop's directory
   • Update claude_desktop_config.json with server path
   • Restart Claude Desktop

4. Start Using:

   Send an email to john@example.com with subject "Hello" and body "Testing Gmail MCP"
   

Architecture

Built with TypeScript and follows MCP specifications:

• Entry Point: src/index.ts - Main MCP server setup and tool definitions
• Gmail Client: src/gmail-client.ts - Gmail API wrapper with OAuth authentication
• Authentication: src/auth.ts - OAuth 2.0 credential management
• Types: src/types.ts - TypeScript interfaces and type definitions

Development

# Development mode with hot reload
npm run dev

# Test with MCP Inspector
npm run inspect

# Build for production
npm run build

Security

• Uses minimal required Gmail scopes (read and send only)
• Tokens stored locally with automatic refresh
• No email content stored permanently
• All operations performed locally

---

Complete User Guide

Overview

This Gmail MCP Server allows Claude Desktop to interact with your Gmail account through secure OAuth 2.0 authentication. You can send emails, search messages, read emails, and manage multiple Gmail accounts.

Prerequisites

• Node.js (version 18 or higher)
• Claude Desktop application installed
• Gmail account with API access enabled
• Google Cloud Console project with Gmail API enabled

Setup Instructions

1. Google Cloud Console Setup

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select an existing one

2. Enable Gmail API:

   • Navigate to "APIs & Services" → "Library"
   • Search for "Gmail API" and enable it

3. Create OAuth 2.0 Credentials:

   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "OAuth 2.0 Client IDs"
   • Choose "Desktop application"
   • Download the credentials JSON file
   • Important: This file will need to be placed in Claude Desktop's directory later

4. Configure OAuth Consent Screen:

   • Go to "APIs & Services" → "OAuth consent screen"
   • Add your email as a test user
   • Set scopes: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send

2. Project Setup

1. Clone and Install:

   git clone <repository-url>
   cd gmail-mcp
   npm install
   

2. Add Google Credentials:

   • Rename your downloaded credentials file to credentials.json
   • Place it in Claude Desktop's working directory (not the project directory)
   • Location varies by OS:
     • macOS: ~/Library/Application Support/Claude/
     • Windows: %APPDATA%\Claude\
     • Linux: ~/.config/claude/
   • Important: Never commit this file to version control

3. Build the Project:

   npm run build
   

4. Test the Setup:

   npm run inspect
   

   This opens the MCP Inspector for testing tools before connecting to Claude Desktop.

3. Claude Desktop Integration

1. Locate Claude Desktop Config:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/claude/claude_desktop_config.json

2. Update Configuration:

   {
     "mcpServers": {
       "gmail": {
         "command": "node",
         "args": ["/absolute/path/to/your/gmail-mcp/build/index.js"]
       }
     }
   }
   

   Replace /absolute/path/to/your/gmail-mcp/ with the actual path to your project.

3. Restart Claude Desktop:

   • Close and reopen Claude Desktop
   • The Gmail MCP server should now be available

First-Time Authentication

When you first use Gmail tools through Claude Desktop:

1. Browser Authentication:

   • A browser window will open automatically
   • Sign in with your Gmail account
   • Grant the requested permissions

2. Token Storage:

   • Authentication tokens are stored in the accounts/ directory within Claude Desktop's directory
   • These tokens auto-refresh and are valid for 6 months of inactivity

Available Tools

Email Operations

Send Email:

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Don't forget our meeting at 2 PM"

Search Emails:

Search for emails from support@company.com in the last week

Read Email:

Read the email with message ID [message-id]

Account Management

List Accounts:

Show me all configured Gmail accounts

Add Account:

Add Gmail account jane@example.com

Remove Account:

Remove Gmail account old@example.com

Set Default Account:

Set primary@example.com as the default account

Usage Examples

Basic Email Operations

1. Send a simple email:

   Send an email to team@company.com with subject "Project Update" and tell them the project is on track
   

2. Search for recent emails:

   Find all emails from my manager in the last 3 days
   

3. Read a specific email:

   Read the latest email from notifications@github.com
   

Multi-Account Usage

1. Send from specific account:

   Send an email from work@company.com to client@example.com about the project status
   

2. Search in specific account:

   Search for invoices in my personal@gmail.com account
   

Advanced Gmail Search

Gmail search queries support operators like:

• from:sender@example.com
• subject:meeting
• has:attachment
• newer_than:7d
• is:unread

Example:

Search for unread emails with attachments from the last week

Security & Privacy

Authentication Security

• Uses OAuth 2.0 with minimal required scopes
• Tokens stored locally in encrypted format
• No passwords stored anywhere
• Automatic token refresh

Data Privacy

• No email content is stored permanently
• All operations are performed locally
• No data sent to third parties
• Audit logs available in Claude Desktop

Best Practices

• Set restrictive file permissions on credentials.json in Claude Desktop's directory
• Regularly review OAuth consent screen
• Remove unused accounts
• Monitor token usage in Google Cloud Console
• Keep credentials.json secure - it's stored in Claude Desktop's directory for access by the MCP server

Troubleshooting

Common Issues

"No account specified and no default account set":

• Solution: Add an account using add_account tool or set a default account

"Authentication failed":

• Check if credentials.json exists in Claude Desktop's directory (not the project directory)
• Verify Gmail API is enabled in Google Cloud Console
• Try removing and re-adding the account

"Token expired":

• Tokens auto-refresh, but manual re-authentication may be needed
• Remove and re-add the account if issues persist

Claude Desktop not detecting MCP server:

• Verify the absolute path in config file
• Check that the build directory exists
• Restart Claude Desktop after config changes

Development and Testing

Test tools without Claude Desktop:

npm run inspect

Development mode with hot reload:

npm run dev

View server logs:

• Check Claude Desktop logs for MCP server output
• Use Inspector tool for detailed request/response debugging

File Structure

Project Directory:

gmail-mcp/
├── build/              # Compiled JavaScript (auto-generated)
├── src/                # TypeScript source code
├── package.json        # Project dependencies
└── CLAUDE.md          # Project instructions for Claude

Claude Desktop Directory (where credentials.json goes):

~/.config/claude/       # Linux
~/Library/Application Support/Claude/  # macOS
%APPDATA%\Claude\       # Windows
├── credentials.json    # Google OAuth credentials (you provide)
├── accounts/           # Account tokens (auto-generated when using tools)
└── claude_desktop_config.json  # Claude Desktop configuration

Limitations

• Rate limits: Gmail API has daily quotas
• Scope limitations: Only read and send permissions
• Token expiry: Tokens expire after 6 months of inactivity
• File attachments: Not currently supported for sending
• HTML emails: Limited formatting support

Getting Help

If you encounter issues:

1. Check the troubleshooting section above
2. Test with the MCP Inspector (npm run inspect)
3. Review Google Cloud Console for API quotas and errors
4. Check Claude Desktop logs for MCP server messages

Advanced Configuration

Custom Scopes

Modify the scopes in src/auth.ts if you need additional Gmail permissions.

Multiple Projects

You can run multiple instances for different Google Cloud projects by using different configuration names in Claude Desktop.

Development

See CLAUDE.md for development guidelines and architecture details.