Gmail MCP Server
A comprehensive Gmail MCP (Model Context Protocol) server that provides Gmail integration for AI assistants like Goose. This server enables reading, searching, and sending emails through the Gmail API.
🚀 Features
- 📧 Send Emails: Send emails directly through Gmail API
- 📋 List Emails: Retrieve recent emails from your inbox
- 📖 Read Emails: Read full content of specific emails
- 🔍 Search Emails: Search emails using Gmail query syntax
- 🖥️ CLI Interface: Command-line tools for terminal usage
- 🤖 MCP Integration: Works with AI assistants via Model Context Protocol
🛠️ Setup
Prerequisites
- Python 3.12+
- Gmail API credentials from Google Cloud Console
- Google account with Gmail access
Installation
-
Clone the repository:
bash git clone https://github.com/Rajganesh-75/gmail-mcp-server.git cd gmail-mcp-server -
Set up virtual environment:
bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate -
Install dependencies:
bash pip install -r requirements.txt -
Set up Gmail API credentials:
- Go to Google Cloud Console
- Create a new project or select existing one
- Enable Gmail API
- Create OAuth 2.0 credentials
- Downloadcredentials.jsonand place it in the project root -
First-time authentication:
bash python test_server.py
This will open a browser for OAuth authentication and createtoken.json.
🖥️ Command Line Usage
Send Email```bash
python gmail_cli.py send "recipient@example.com" "Subject" "Message body"
### List Recent Emails```bash
python gmail_cli.py list 10
Read Specific Email```bash
python gmail_cli.py read "message_id_here"
### Search Emails```bash
python gmail_cli.py search "from:github.com" 5
python gmail_cli.py search "subject:important"
Get Help```bash
python gmail_cli.py
## 🤖 MCP Integration (Goose/AI Assistants)
### Start MCP Server```bash
python run_server.py
Add to Goose Configuration
Add this to your ~/.config/goose/config.yaml:```yaml
extensions:
gmail_custom:
enabled: true
type: stdio
name: Gmail Custom
cmd: python
args:
- /path/to/gmail-mcp-server/run_server.py
envs: {}
env_keys: []
timeout: 300
description: Custom Gmail MCP server with full read/write access
bundled: false
available_tools: []
### Available MCP Tools
- `list_emails(count)` - List recent emails
- `read_email(message_id)` - Read full email content
- `send_email(to, subject, body)` - Send emails
- `search_emails(query, count)` - Search emails
## 📁 Project Structure```
gmail-mcp-server/
├── server.py # Main MCP server with Gmail functions
├── gmail_cli.py # Command-line interface
├── run_server.py # MCP server runner
├── test_server.py # Test script for functionality
├── send_email_cli.py # Simple email sender CLI
├── credentials.json # Google OAuth credentials (not in repo)
├── token.json # Authentication token (not in repo)
├── pyproject.toml # Project dependencies
├── requirements.txt # Pip requirements
└── README.md # This file
🔒 Security Notes
credentials.jsonandtoken.jsoncontain sensitive information- These files are excluded from git via
.gitignore - Never commit authentication files to public repositories
- Use environment variables for production deployments
🧪 Testing
Run the test suite to verify everything works:bash
python test_server.py
This will test:
- Gmail API authentication
- MCP server functionality
- Email listing capability
📋 Requirements
google-api-python-client>=2.181.0google-auth-httplib2>=0.2.0google-auth-oauthlib>=1.2.2mcp[cli]>=1.13.1
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Built using Google Gmail API
- Implements Model Context Protocol (MCP)
- Compatible with Goose AI assistant
- Inspired by the need for seamless email integration in AI workflows
📞 Support
For issues and questions:
- Create an issue on GitHub
- Check the troubleshooting section below
🔧 Troubleshooting
Authentication Issues
- Ensure
credentials.jsonis properly configured - Check that Gmail API is enabled in Google Cloud Console
- Verify OAuth scopes include Gmail access
MCP Connection Issues
- Ensure the server is running (
python run_server.py) - Check Goose configuration file syntax
- Verify file paths in configuration
Permission Errors
- Check Gmail API quotas in Google Cloud Console
- Ensure OAuth consent screen is properly configured
- Verify account has necessary Gmail permissions
