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:

Go to APIs & Services → OAuth consent screen
Select External user type
Fill in required fields:
- App name: Gmail MCP Server
- User support email: Your email
- Developer contact email: Your email
Add these authorized scopes:
- https://www.googleapis.com/auth/gmail.modify
- https://www.googleapis.com/auth/gmail.settings.basic
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

Go to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Choose application type:
- Web application (recommended)
Configure authorized redirect URIs:
- Add: http://localhost:3000/oauth2callback
Download the JSON credentials file
Rename it to gcp-oauth.keys.json
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:

Display a helpful pre-flight checklist
Open your browser for Google authentication
Save credentials to ~/.gmail-mcp/credentials.json
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:

Visit OAuth Consent Screen
Scroll to "Test users"
Click "ADD USERS"
Enter your Gmail address
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:

Go to OAuth consent screen configuration
Add Privacy Policy URL (can use https://policies.google.com/privacy as placeholder)
Ensure Developer contact email is filled
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:

Check your internet connection
Verify OAuth credentials are still valid in Google Cloud Console
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:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Build and test: npm run build
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
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:

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!

Gmail MCP Server

📚 Documentation

Why This Project?

Quick Start

Prerequisites

Installation

Google Cloud Setup

1. Create a Google Cloud Project

2. Configure OAuth Consent Screen

3. Create OAuth Credentials

Authentication

First-Time Setup

Re-authentication

Configure Claude Desktop

Features

Email Operations

Sending & Drafting

Reading & Searching

Organization

Advanced Features

Smart Authentication

Batch Processing

Filter Templates

API Reference

Available Tools

send_email

draft_email

read_email

search_emails

modify_email

delete_email

list_email_labels

create_label

batch_modify_emails

batch_delete_emails

create_filter

download_attachment

Troubleshooting

Authentication Issues

Error: "403: Access blocked"

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

Error: "Credentials are invalid or expired"

Error: "Port 3000 already in use"

Operation Issues

Attachment Won't Send

Token Refresh Failed

Development

Project Structure

Building from Source

Running in Development

Testing Authentication

Security Considerations

Contributing

Reporting Issues

License

Acknowledgments

Support

Star History

安装包 （如果需要）

Cursor 配置 (mcp.json)

`send_email`

`draft_email`

`read_email`

`search_emails`

`modify_email`

`delete_email`

`list_email_labels`

`create_label`

`batch_modify_emails`

`batch_delete_emails`

`create_filter`

`download_attachment`

安装包（如果需要）