Rajganesh-75/gmail-mcp-server

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

1. Clone the repository:

   git clone https://github.com/Rajganesh-75/gmail-mcp-server.git
   cd gmail-mcp-server
   

2. Set up virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. 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
   • Download credentials.json and place it in the project root

5. First-time authentication:

   python test_server.py
   

   This will open a browser for OAuth authentication and create token.json.

🖥️ Command Line Usage

Send Email

python gmail_cli.py send "recipient@example.com" "Subject" "Message body"

List Recent Emails

python gmail_cli.py list 10

Read Specific Email

python gmail_cli.py read "message_id_here"

Search Emails

python gmail_cli.py search "from:github.com" 5
python gmail_cli.py search "subject:important"

Get Help

python gmail_cli.py

🤖 MCP Integration (Goose/AI Assistants)

Start MCP Server

python run_server.py

Add to Goose Configuration

Add this to your ~/.config/goose/config.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.json and token.json contain 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:

python test_server.py

This will test:

• Gmail API authentication
• MCP server functionality
• Email listing capability

📋 Requirements

• google-api-python-client>=2.181.0
• google-auth-httplib2>=0.2.0
• google-auth-oauthlib>=1.2.2
• mcp[cli]>=1.13.1

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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.json is 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