Gmail MCP Server

2 forks

6 stars

Free

What is gmail-mcp-server

gmail-mcp-server is a specialized server designed to integrate Gmail capabilities into clients that use the Model Context Protocol (MCP), such as the Claude Desktop AI assistant. Created by ajbr0wn, this server enables seamless access to Gmail features, allowing AI-powered applications to interact with your email data securely and efficiently. By leveraging secure OAuth2 authentication, gmail-mcp-server ensures that your Gmail access is both safe and compliant with privacy standards.

How to Use gmail-mcp-server

To set up and use gmail-mcp-server, follow these steps:

Google Cloud Project Setup: First, establish a Google Cloud Project and enable the Gmail API. Create OAuth 2.0 credentials for a desktop application and download the credentials.json file.
Installation: Set up a Python environment using Conda. Install the server package by navigating to the directory and executing the installation command.
```
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail
cd gmail-mcp-server
pip install -e .
```
Configuration for Claude Desktop: Update your claude_desktop_config.json file to include the necessary command paths and environment variables for the server to function.
First Run: Upon initial use, authorize the application via your browser. This process saves your credentials for future access, allowing the server to function seamlessly without repeated authorizations.

Key Features of gmail-mcp-server

View Recent Emails: Access your 10 most recent emails directly through the server.
Search Emails: Use Gmail's standard search syntax to find specific emails based on your queries.
Secure OAuth2 Authentication: The server employs OAuth2 for secure access, ensuring that your Gmail data is protected. You authorize access during the first use, and the credentials are saved locally for future operations.
Environment Variables: Configure paths for credential and token files to manage authentication and access efficiently.
Resource and Tool Access: The server provides tools for accessing email resources and performing searches, enabling AI assistants to retrieve real-time email data.
Development and Logging: Built for developers, the server logs detailed operational information and supports contributions to enhance its features.

By integrating gmail-mcp-server into your MCP client setup, you can harness the power of Gmail within your AI applications, making email management more intuitive and integrated into your digital workflows.

An MCP (Model Context Protocol) server that provides Gmail integration capabilities to MCP clients like Claude Desktop.

Features

View recent emails from your Gmail inbox
Search emails using Gmail's search syntax
Secure OAuth2 authentication with Gmail API

Setup

1. Google Cloud Project Setup

Create a Google Cloud Project at
Enable the Gmail API
Create OAuth 2.0 credentials:

Application type: Desktop application
Download the credentials as credentials.json

2. Installation

# Create a conda environment
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail
# Install the package
cd gmail-mcp-server
pip install -e .

3. Configuration for Claude Desktop

Add to your claude_desktop_config.json:

 "mcpServers": {
 "gmail": {
 "command": "/path/to/conda/envs/mcp-gmail/bin/python",
 "args": ["-m", "gmail_mcp_server.server"],
 "env": {
 "PYTHONPATH": "/path/to/gmail-mcp-server/src",
 "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
 "GMAIL_TOKEN_FILE": "/path/to/token.json"

Replace /path/to/ with your actual paths. The token file will be created automatically when you first authenticate.

4. First Run

When you first try to access Gmail through Claude, you'll be prompted to authorize the application in your browser. After authorization, your credentials will be saved to the token file for future use.

Available Resources

gmail://inbox/recent - Returns your 10 most recent emails

Available Tools

search_emails
Description: Search Gmail emails with a query
Parameters:
query (required): Gmail search query (uses Gmail's standard search syntax)
max_results (optional): Maximum number of results to return (default: 10) Example search:

Could you show me any emails from sanrio in the last two days?

Security

This server requires OAuth2 authentication with Gmail:

You'll be prompted to authorize access in your browser on first use
Credentials are stored locally in the specified token file
Access can be revoked at any time through your Google Account settings
Only read access to Gmail is requested (no write permissions)

Environment Variables

GMAIL_CREDENTIALS_FILE (required): Path to your Google OAuth credentials file
GMAIL_TOKEN_FILE (required): Path where the authentication token will be saved For testing, you can run the server directly:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Development

The server uses the Model Context Protocol to provide:

Resource access to recent emails
Tool support for email search
Secure OAuth2 authentication flow
Automatic token refresh

Logging

The server logs detailed information about its operations to stderr, including:

Server startup information
Authentication status
Resource and tool usage
Any errors or issues

Contributing

Pull requests are welcome! Please ensure to:

Update documentation for any new features
Add appropriate error handling
Test OAuth flow with new features
Follow existing code style

How to Use

To use the gmail-mcp-server, follow these steps:

Visit https://github.com/ajbr0wn/gmail-mcp-serverhttps://github.com/ajbr0w...
Follow the setup instructions to create an account (if required)
Connect the MCP server to your Claude Desktop application
Start using gmail-mcp-server capabilities within your Claude conversations

Additional Information

Created

December 1, 2024

Company

ajbr0wn

Related MCP Servers

Start building your own MCP Server

Interested in creating your own MCP Server? Check out the official documentation and resources.

Learn More