Gmail MCP Server
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 https://console.cloud.google.com/
- Enable the Gmail API
- Create OAuth 2.0 credentials: - Application type: Desktop application - Download the credentials as `credentials.json`
2. Installation
3. Configuration for Claude Desktop
Add to your `claude_desktop_config.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:
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:
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