Gmail MCP Server

The Gmail MCP server that actually works - No OpenAI API required, rock-solid authentication, zero configuration hassles

Transform your Gmail into an AI-powered inbox with natural language commands through Claude Desktop. Send emails, manage labels, automate organization, download attachments - all without leaving your conversation.

✨ Key Highlights:

• 🔐 Bulletproof Authentication - Intelligent token management with auto-refresh
• 🚀 Production Ready - TypeScript, comprehensive error handling, battle-tested
• 💰 100% Free - No OpenAI API costs, no hidden fees
• 🔒 Privacy First - Direct Gmail API, no third-party AI dependencies
• 📦 Feature Complete - Attachments, labels, filters, batch operations, and more

Why choose this over alternatives? | See it in action | Start in 5 minutes

---

📚 Documentation

• Complete API Reference - Detailed documentation for all tools
• Troubleshooting Guide - Solutions for common issues
• Example Use Cases - Practical examples and workflows
• Comparison with Alternatives - Why choose this server
• Showcase - See what you can build
• Contributing Guide - How to contribute
• Code of Conduct - Community guidelines
• Security Policy - Security best practices
• Changelog - Version history and updates

---

Why This Project?

Traditional Gmail integrations struggle with authentication complexity and token management. This server solves those problems with:

• Intelligent Token Management: Automatic validation and refresh - no more expired credential errors
• User-Friendly Error Handling: Clear, actionable error messages with step-by-step solutions
• Comprehensive Email Operations: Send, read, search, organize, and automate your inbox
• Production-Ready: Built with TypeScript, proper error handling, and extensive testing

---

Quick Start

Prerequisites

• Node.js 16 or higher
• A Google Cloud Platform account
• Claude Desktop application

Installation

Option 1: Run Directly (Recommended for Testing)

git clone https://github.com/devdattatalele/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

Option 2: Install as Package

npm install -g @devdattatalele/gmail-mcp-server

Google Cloud Setup

Before using this server, you need to set up OAuth credentials:

1. Create a Google Cloud Project

Navigate to Google Cloud Console and:

• Create a new project (or select existing)
• Enable the Gmail API for your project
• Note your project ID for later

2. Configure OAuth Consent Screen

This is the most critical step - skip it and you'll get authentication errors:

1. Go to APIs & Services → OAuth consent screen
2. Select External user type
3. Fill in required fields:
   • App name: Gmail MCP Server
   • User support email: Your email
   • Developer contact email: Your email
4. Add these authorized scopes:
   • https://www.googleapis.com/auth/gmail.modify
   • https://www.googleapis.com/auth/gmail.settings.basic
5. Add yourself as a test user:
   • Scroll to "Test users" section
   • Click "ADD USERS"
   • Enter your Gmail address
   • Click "Save"

Critical: Without adding yourself as a test user, you'll encounter "Error 403: Access blocked" during authentication.

3. Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Choose application type:
   • Web application (recommended)
4. Configure authorized redirect URIs:
   • Add: http://localhost:3000/oauth2callback
5. Download the JSON credentials file
6. Rename it to gcp-oauth.keys.json
7. Place it in your project directory or ~/.gmail-mcp/

Authentication

First-Time Setup

# Navigate to project directory
cd gmail-mcp-server

# Run authentication
node dist/index.js auth

The server will:

1. Display a helpful pre-flight checklist
2. Open your browser for Google authentication
3. Save credentials to ~/.gmail-mcp/credentials.json
4. Automatically validate and refresh tokens as needed

Re-authentication

If you need to switch accounts or fix authentication issues:

node dist/index.js auth --force

The --force flag removes existing credentials and starts fresh.

Configure Claude Desktop

Add this to your Claude Desktop configuration file:

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

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

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

---

Features

Email Operations

Sending & Drafting

• Send emails with attachments, CC, BCC
• Draft emails for later editing
• HTML and plain text support
• Reply to threads with threading support
• Attachment handling up to 25MB per email

Reading & Searching

• Read emails with full MIME structure parsing
• Search using Gmail's powerful query syntax
• Download attachments to local filesystem
• View attachment metadata (filename, size, type, ID)

Organization

• Label management: Create, update, delete, list
• Batch operations: Process multiple emails efficiently
• Email filters: Automate inbox organization
• Archive, delete, mark as read/unread

Advanced Features

Smart Authentication

// Automatic token validation on server start
// Auto-refresh expired tokens
// Clear error messages for common issues
// Force re-authentication option

Batch Processing

// Process up to 50 emails at once
// Automatic retry on individual failures
// Detailed success/failure reporting

Filter Templates

Pre-built templates for common scenarios:

• Auto-organize by sender
• Filter by subject keywords
• Handle large attachments
• Manage mailing lists
• Content-based filtering

---

API Reference

Available Tools

send_email

Send an email immediately.

Parameters:

• to (string[]): Recipient email addresses
• subject (string): Email subject
• body (string): Email body (plain text)
• htmlBody (string, optional): HTML version of body
• cc (string[], optional): CC recipients
• bcc (string[], optional): BCC recipients
• attachments (string[], optional): File paths to attach
• threadId (string, optional): Reply to thread

Example:

{
  "to": ["colleague@example.com"],
  "subject": "Project Update",
  "body": "Here's the latest on the project...",
  "attachments": ["/path/to/report.pdf"]
}

draft_email

Create a draft email without sending.

Same parameters as send_email.

read_email

Retrieve email content by ID.

Parameters:

• messageId (string): Gmail message ID

Returns: Full email content with headers, body, and attachment info.

search_emails

Search for emails using Gmail query syntax.

Parameters:

• query (string): Gmail search query
• maxResults (number, optional): Maximum results (default: 10)

Example Queries:

from:boss@company.com after:2024/01/01
has:attachment subject:invoice
is:unread label:important

modify_email

Change email labels (move, archive, etc.).

Parameters:

• messageId (string): Gmail message ID
• addLabelIds (string[], optional): Labels to add
• removeLabelIds (string[], optional): Labels to remove

delete_email

Permanently delete an email.

Parameters:

• messageId (string): Gmail message ID

list_email_labels

Get all available Gmail labels (system and user-created).

No parameters required.

create_label

Create a new Gmail label.

Parameters:

• name (string): Label name
• messageListVisibility ('show' | 'hide', optional)
• labelListVisibility ('labelShow' | 'labelShowIfUnread' | 'labelHide', optional)

batch_modify_emails

Modify labels for multiple emails at once.

Parameters:

• messageIds (string[]): Array of message IDs
• addLabelIds (string[], optional)
• removeLabelIds (string[], optional)
• batchSize (number, optional): Batch size (default: 50)

batch_delete_emails

Delete multiple emails at once.

Parameters:

• messageIds (string[]): Array of message IDs
• batchSize (number, optional): Batch size (default: 50)

create_filter

Create a Gmail filter with custom criteria.

Parameters:

• criteria: Match conditions (from, to, subject, query, hasAttachment, size, etc.)
• action: Actions to perform (addLabelIds, removeLabelIds, forward)

download_attachment

Download an email attachment to local filesystem.

Parameters:

• messageId (string): Gmail message ID
• attachmentId (string): Attachment ID (from read_email)
• savePath (string, optional): Download directory
• filename (string, optional): Custom filename

---

Troubleshooting

Authentication Issues

Error: "403: Access blocked"

Cause: Your app is in "Testing" mode and you're not added as a test user.

Solution:

1. Visit OAuth Consent Screen
2. Scroll to "Test users"
3. Click "ADD USERS"
4. Enter your Gmail address
5. Save and retry authentication

Error: "400: invalid_request" or "doesn't comply with OAuth 2.0 policy"

Cause: OAuth consent screen is missing required fields (usually privacy policy).

Solution:

1. Go to OAuth consent screen configuration
2. Add Privacy Policy URL (can use https://policies.google.com/privacy as placeholder)
3. Ensure Developer contact email is filled
4. Save and retry

Error: "Credentials are invalid or expired"

Solution:

node dist/index.js auth --force

This removes old credentials and starts fresh authentication.

Error: "Port 3000 already in use"

Solution:

# macOS/Linux
lsof -ti:3000 | xargs kill

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Operation Issues

Attachment Won't Send

Possible causes:

• File path is incorrect or inaccessible
• File exceeds 25MB Gmail limit
• Permission issues reading the file

Solution:

• Verify file path is absolute
• Check file permissions
• Ensure file size is under 25MB

Token Refresh Failed

The server automatically refreshes expired tokens. If this fails:

1. Check your internet connection
2. Verify OAuth credentials are still valid in Google Cloud Console
3. Run node dist/index.js auth --force to re-authenticate

---

Development

Project Structure

gmail-mcp-server/
├── src/
│   ├── index.ts              # Main server implementation
│   ├── utl.ts                # Email utilities
│   ├── label-manager.ts      # Label operations
│   ├── filter-manager.ts     # Filter operations
│   └── evals/                # Evaluation tests
├── dist/                     # Compiled JavaScript
├── gcp-oauth.keys.json       # Your OAuth credentials (gitignored)
├── package.json
├── tsconfig.json
└── README.md

Building from Source

git clone https://github.com/devdattatalele/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

Running in Development

npm run dev    # Watch mode - rebuilds on changes

Testing Authentication

npm run auth   # Equivalent to: node dist/index.js auth

---

Security Considerations

• OAuth credentials are stored in ~/.gmail-mcp/ with user-only permissions
• Never commit gcp-oauth.keys.json or credentials.json to version control
• Tokens are auto-refreshed - no need to manually handle expiration
• Attachments are processed locally and never stored by the server
• Review access regularly in Google Account Settings

---

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Build and test: npm run build
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Reporting Issues

Found a bug or have a suggestion? Open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Your environment (OS, Node version, etc.)

---

License

MIT License - see LICENSE file for details.

---

Acknowledgments

Built using:

• Model Context Protocol SDK
• Google APIs Node.js Client
• Google Auth Library

---

Support

• Documentation: Full API Reference
• Troubleshooting: Common Issues & Solutions
• Examples: Practical Use Cases
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Report Vulnerabilities
• Email: taleledevdatta@gmail.com

---

Star History

If this project helped you, please consider giving it a ⭐!

---

Made with ❤️ by Devdatta Talele

Special thanks to all contributors who make this project better!