Gmail MCP Server

MCP Gmail Server

A Model Context Protocol (MCP) server for integrating Gmail with Claude and other MCP-compatible AI assistants.

🚀 Features

List emails: Retrieve emails from your inbox
Send emails: Compose and send emails
Email management: Delete, archive, mark as read
Batch operations: Process multiple emails in a single operation
Label management: List and move emails to specific labels

📋 Prerequisites

Node.js 18 or higher
A Google account with Gmail API enabled
OAuth2 credentials (Client ID, Client Secret)

🔧 Installation

Clone the repository:

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

Install dependencies:

npm install

Configure your OAuth2 credentials (see Configuration section)

⚙️ Configuration

Step 1: Create a Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API for your project
Go to "Credentials" and create an OAuth2 Client ID
Application type: "Desktop app"
Important: Add http://localhost:3000 to the authorized redirect URIs

Step 2: Get the Refresh Token

Run the authentication script:

npm run get-token

Follow the on-screen instructions to:

Enter your Client ID
Enter your Client Secret
Authorize access in your browser
Retrieve your Refresh Token

Step 3: Configure Environment Variables

Create a .env file at the project root:

GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
GMAIL_REFRESH_TOKEN=your_refresh_token

🎯 Usage with Claude Desktop

Add the server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp/build/src/index.js"],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id",
        "GMAIL_CLIENT_SECRET": "your_client_secret",
        "GMAIL_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Restart Claude Desktop

📚 Available Tools

list_emails

List emails from inbox

maxResults: Maximum number of emails (default: 10)
query: Gmail search query (optional)

send_email

Send an email

to: Recipient email address
subject: Email subject
body: Email body

delete_email

Delete an email

id: Email ID

archive_email

Archive an email

id: Email ID

mark_as_read

Mark an email as read

id: Email ID

Batch Operations

delete_emails_batch: Delete multiple emails
archive_emails_batch: Archive multiple emails
mark_as_read_batch: Mark multiple emails as read

Label Management

list_labels: List all available labels
move_to_label: Move an email to a label
move_to_label_batch: Move multiple emails to a label

🛠️ Useful Scripts

# Build the project
npm run build

# Build in watch mode
npm run watch

# Get a new refresh token
npm run get-token

# Clean and rebuild
npm run rebuild

# Inspect the MCP server
npm run inspector

📁 Project Structure

mcp-gmail/
├── src/              # TypeScript source code
│   └── index.ts      # MCP server entry point
├── scripts/          # Utility scripts
│   └── get-refresh-token.ts
├── build/            # Compiled JavaScript code
├── .env              # Environment variables (ignored by git)
├── .env.example      # Configuration example
├── package.json      # npm configuration
├── tsconfig.json     # TypeScript configuration
└── README.md         # This file

🔒 Security

Never share your OAuth2 credentials
The .env file is automatically ignored by Git
Use minimal permissions for the Gmail API

📝 License

MIT - See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or pull request.

🐛 Troubleshooting

If you encounter issues:

Verify that the Gmail API is enabled in your Google Cloud project
Ensure redirect URIs include http://localhost:3000
Check that your refresh token is valid

📧 Contact

Julien Renaud - GitHub

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A Model Context Protocol server that enables Claude to interact with Gmail through a secure OAuth2 connection, providing email management capabilities like listing, sending, deleting, and organizing emails.

Related MCP Servers

@kazuph/mcp-gmail-gas
kazuph
A
security
A
license
A
quality
Model Context Protocol server for Gmail integration. This allows Claude Desktop (or any MCP client) to interact with your Gmail account through Google Apps Script.
Last updated -
3
552
11
JavaScript
MIT License
Google Tasks MCP Server
arpitbatra123
A
security
A
license
A
quality
A Model Context Protocol server that bridges Claude with Google Tasks, allowing users to manage task lists and tasks directly through Claude interface.
Last updated -
15
15
TypeScript
MIT License
ClaudePost
ZilongXue
A
security
A
license
A
quality
A Model Context Protocol server that provides a seamless email management interface through Claude, allowing users to search, read, and send emails directly through natural language conversations.
Last updated -
4
90
Python
MIT License
Enhanced Gmail MCP Server
theposch
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities including sending, reading, organizing, searching, and managing drafts and labels.
Last updated -
4
Python
GPL 3.0

View all related MCP servers