JaviEzpeleta/gmail-mcp-server

📧 Gmail MCP Server

A powerful MCP (Model Context Protocol) server that enables AI assistants to interact with Gmail through OAuth2 authentication with safety-first design. Built with TypeScript and designed for seamless integration with Claude Desktop and other MCP-compatible clients.

📑 Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
  • Google Cloud Setup
  • OAuth2 Credentials
  • Generate Refresh Token
• Usage
  • Standalone Server
  • Claude Desktop Integration
• Available Tools
• Examples
• Troubleshooting
• Development

✨ Features

• 🛡️ Safety First - Draft-only mode by default prevents accidental email sends
• 📝 Smart Drafts - Create drafts for new emails and replies with custom content
• 📬 List Emails - Retrieve recent emails with advanced filtering options
• 📖 Get Email Details - Fetch complete email content including attachments info
• 🔍 Search Emails - Use Gmail's powerful search syntax to find specific emails
• ✉️ Send Emails - Direct sending (disabled by default, enable with caution)
• 🔐 Secure OAuth2 - Industry-standard authentication with refresh token support
• 🎯 Type-Safe - Full TypeScript implementation with strict typing
• 🚀 High Performance - Optimized with parallel processing and smart caching

📋 Prerequisites

Before you begin, ensure you have:

• Node.js 18.0 or higher
• npm or yarn package manager
• Google Account with Gmail enabled
• Google Cloud Console access
• Claude Desktop (optional, for integration)

📦 Installation

1. Clone the repository:

git clone https://github.com/JaviEzpeleta/gmail-mcp-server.git
cd gmail-mcp-server

2. Install dependencies:

npm install

3. Create environment file:

cp .env.example .env

🛡️ Security Note: By default, direct email sending is disabled for safety. The server will create drafts instead, which you can review and send manually from Gmail.

⚙️ Configuration

1. Google Cloud Console Setup

1. Create or select a project:

   • Go to Google Cloud Console
   • Click on the project dropdown and select "New Project"
   • Give your project a name (e.g., "Gmail MCP Server")
   • Click "Create"

2. Enable Gmail API:

   • In the sidebar, navigate to APIs & Services → Library
   • Search for "Gmail API"
   • Click on Gmail API from the results
   • Click Enable
   • Wait for the API to be enabled (usually takes a few seconds)

2. Create OAuth2 Credentials

1. Configure OAuth consent screen:

   • Go to APIs & Services → OAuth consent screen
   • Select "External" user type (unless you have a Google Workspace account)
   • Fill in the required fields:
     • App name: "Gmail MCP Server"
     • User support email: Your email
     • Developer contact: Your email
   • Add scopes:
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.modify
   • Add test users (important!):
     • Add your Gmail address and any other accounts you want to use
   • Save and continue through all steps

2. Create OAuth client:

   • Go to APIs & Services → Credentials
   • Click + CREATE CREDENTIALS → OAuth client ID
   • Application type: Web application ⚠️ (NOT Desktop app)
   • Name: "Gmail MCP Web Client"
   • Configure Authorized redirect URIs:
     • Click + ADD URI
     • Add: http://localhost:8765/oauth2callback (default port)
     • If you plan to use a custom port, add: http://localhost:YOUR_PORT/oauth2callback
   • Click Create
   • Download the credentials (you'll see a download button or JSON option)
   • Save the client_id and client_secret from the downloaded file

⚠️ Important: Desktop app type doesn't allow custom redirect URIs, but we need localhost:PORT/oauth2callback for the OAuth flow to work. That's why we use Web application instead.

3. Generate Refresh Token

1. Add credentials to .env:

GMAIL_CLIENT_ID=your_client_id_here
GMAIL_CLIENT_SECRET=your_client_secret_here
GMAIL_REFRESH_TOKEN=
# Security: Keep this false unless you need direct sending
GMAIL_ALLOW_DIRECT_SEND=false
# OAuth setup port (must match the redirect URI you configured above)
OAUTH_REDIRECT_PORT=8765

💡 Port Configuration: The OAUTH_REDIRECT_PORT must match the port you configured in the Google Cloud Console redirect URI. If you used http://localhost:8765/oauth2callback, keep it as 8765. If you used a different port, update this value accordingly.

2. Run the setup script:

npm run setup
# or
npm run dev src/get-refresh-token-desktop.ts

3. Authorize the application:

   • A browser window will open automatically
   • Sign in with your Google account
   • Grant all requested permissions
   • You'll be redirected to a success page

4. Save the refresh token:

   • The terminal will display your refresh token
   • Copy the complete GMAIL_REFRESH_TOKEN value
   • Add it to your .env file

🚀 Usage

Standalone Server

1. Build the project:

npm run build

2. Start the server:

npm start

The server will start and listen for MCP commands via stdio.

Claude Desktop Integration

1. Build the project first:

npm run build

2. 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

3. Edit the configuration file:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id",
        "GMAIL_CLIENT_SECRET": "your_client_secret",
        "GMAIL_REFRESH_TOKEN": "your_refresh_token",
        "GMAIL_ALLOW_DIRECT_SEND": "false"
      }
    }
  }
}

4. Restart Claude Desktop

5. Verify the connection:

   • Open Claude Desktop
   • Look for the 🔌 icon indicating MCP connection
   • Try: "List my recent emails"

🛠️ Available Tools

🛡️ Safety Notice: Tools marked with 🛡️ create drafts by default for your safety. Direct sending tools marked with 🚨 are disabled by default.

📬 list_emails

List recent emails with optional filtering.

Parameters:

• maxResults (number, 1-100): Maximum emails to return (default: 10)
• query (string): Gmail search query (e.g., "is:unread")
• includeSpamTrash (boolean): Include SPAM/TRASH folders (default: false)

Example:

List my 5 most recent unread emails

📖 get_email_details

Get complete details and content of a specific email.

Parameters:

• emailId (string, required): The email ID to retrieve
• format (string): Level of detail - "full", "minimal", or "metadata" (default: "full")

Example:

Get the full content of email ID 18abc123def

🛡️ create_draft

Create an email draft with optional CC/BCC recipients (recommended for AI assistants).

Parameters:

• to (string, required): Recipient email address
• subject (string, required): Email subject
• body (string, required): Email body (plain text or HTML)
• cc (string): CC recipients (comma-separated)
• bcc (string): BCC recipients (comma-separated)

Example:

Create a draft email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"

🚨 send_email (Disabled by Default)

Send an email directly with optional CC/BCC recipients.

⚠️ Security Warning: This tool is disabled by default. Set GMAIL_ALLOW_DIRECT_SEND=true to enable.

Parameters:

• to (string, required): Recipient email address
• subject (string, required): Email subject
• body (string, required): Email body (plain text or HTML)
• cc (string): CC recipients (comma-separated)
• bcc (string): BCC recipients (comma-separated)

Example:

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"

🔍 search_emails

Search emails using Gmail's advanced search syntax.

Parameters:

• query (string, required): Gmail search query
• maxResults (number, 1-100): Maximum results (default: 10)
• includeSpamTrash (boolean): Include SPAM/TRASH (default: false)

Example Gmail search queries:

• from:user@example.com - Emails from a specific sender
• subject:"important meeting" - Emails with exact phrase in subject
• has:attachment - Emails with attachments
• is:unread - Unread emails
• newer_than:2d - Emails from last 2 days
• label:work - Emails with specific label

🛡️ find_and_draft_reply

Find the latest email from a sender and create a draft reply with optional custom content.

Parameters:

• senderName (string, required): Sender name or email address
• replyBody (string, optional): Custom reply content (template used if not provided)

Example:

Create a draft reply to the latest email from John Smith saying "Thanks for your message. I'll get back to you soon."

📚 Examples

Basic Usage Examples

List recent emails:

Show me my 10 most recent emails

Search for specific emails:

Search for emails from alice@example.com with attachments

Create a draft email:

Create a draft email to bob@example.com saying "Thanks for your help!"

Create a draft reply:

Draft a reply to the latest email from support@company.com

Advanced Usage Examples

Complex search:

Find all unread emails from the last week with "invoice" in the subject

Draft with CC:

Create a draft email to team@company.com with CC to manager@company.com about the project update

Get email details:

Show me the full content of the most recent email from my boss

🔧 Troubleshooting

Common Issues and Solutions

❌ Error: Missing required environment variables

Solution: Ensure all required environment variables are set in your .env file:

• GMAIL_CLIENT_ID
• GMAIL_CLIENT_SECRET
• GMAIL_REFRESH_TOKEN
• GMAIL_ALLOW_DIRECT_SEND (optional, defaults to false)
• OAUTH_REDIRECT_PORT (optional, defaults to 8765)

❌ Error: redirect_uri_mismatch

Problem: OAuth setup fails with "The redirect URI in the request does not match the ones authorized for the OAuth client."

Solution:

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Click on your OAuth client
3. In "Authorized redirect URIs", ensure you have: http://localhost:8765/oauth2callback
4. If using a custom port, add: http://localhost:YOUR_PORT/oauth2callback
5. Make sure your .env file has the matching OAUTH_REDIRECT_PORT=8765
6. Important: OAuth client must be Web application type, not Desktop app

This error commonly occurs when following old documentation that suggests using "Desktop app" type, which doesn't support custom redirect URIs.

🛡️ Security: Direct email sending is disabled

This is normal and safe behavior. By default, the server creates drafts instead of sending emails directly.

Solutions:

• Recommended: Use create_draft tool instead of send_email
• Alternative: Set GMAIL_ALLOW_DIRECT_SEND=true in your .env file (not recommended for AI assistants)

❌ Error 403: access_denied

Solution:

1. Go to Google Cloud Console → OAuth consent screen
2. Add your email as a test user
3. Re-run the token generation process

❌ Error: invalid_grant

Solution: Your refresh token has expired or is invalid

1. Delete the old refresh token from .env
2. Run npm run setup again
3. Complete the authorization flow
4. Update .env with the new token

❌ Gmail API not enabled

Solution:

1. Go to Google Cloud Console
2. Navigate to APIs & Services → Library
3. Search for "Gmail API"
4. Click Enable

❌ Claude Desktop doesn't show the MCP server

Solution:

1. Verify the config file path is correct
2. Ensure all paths in the config are absolute paths
3. Check that the built files exist in dist/
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors

❌ Rate limit exceeded

Solution:

• Gmail API has quotas (250 quota units per user per second)
• Implement exponential backoff for retries
• Reduce the number of parallel requests

🔒 Security Guidelines

Draft-First Approach

This server implements a safety-first design to prevent accidental email sends:

• Default behavior: Creates drafts that require manual review
• Protection: send_email tool is disabled by default
• User control: Explicit environment variable required for direct sending

Recommended Usage

✅ Safe for AI assistants:

• create_draft - Creates email drafts
• find_and_draft_reply - Creates reply drafts
• list_emails, search_emails, get_email_details - Read-only operations

⚠️ Use with caution:

• send_email - Only enable if you fully trust the AI assistant and understand the risks

Best Practices

1. Keep GMAIL_ALLOW_DIRECT_SEND=false unless absolutely necessary
2. Review all drafts before sending manually from Gmail
3. Test thoroughly in a safe environment before production use
4. Monitor usage and check for unexpected behavior

🔨 Development

Available Scripts

# Development with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

# Generate OAuth refresh token
npm run setup

# Run tests
npm test

# Lint code
npm run lint

Project Structure

gmail-mcp-server/
├── src/
│   ├── index.ts                 # Main server implementation
│   └── get-refresh-token-desktop.ts # OAuth setup utility
├── dist/                        # Compiled JavaScript (generated)
├── examples/                    # Usage examples
├── docs/                       # Additional documentation
├── .env.example                # Environment variables template
├── tsconfig.json              # TypeScript configuration
├── package.json              # Project dependencies
└── README.md                # This file

Testing

Test the connection and basic functionality:

# Test Gmail connection
npm run dev test-gmail-connection.ts

# Test with MCP client
npm run dev test-list-emails.js

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Google Gmail API for email functionality
• Model Context Protocol for the MCP specification
• Anthropic for Claude and MCP development

📞 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing issues for solutions
• Read the Gmail API documentation

Made with ❤️ by Javi Ezpeleta