Gmail MCP Server 📧

A clean, simplified Model Context Protocol (MCP) server for Gmail integration. Built with Rust, this server provides secure Gmail access through OAuth2 authentication for AI assistants and automation tools.

🎯 Learning Journey & Attribution

📚 Rust Learning Exercise: This project serves as a hands-on exercise in my journey of learning Rust programming. It demonstrates practical application of Rust concepts including async programming, error handling, OAuth2 implementation, and clean code architecture.

🙏 Inspired by Rig Framework: This implementation replicates and adapts examples from the excellent Rig framework by 0xPlaygrounds. Rig is a powerful Rust framework for building portable, modular & lightweight AI agents with support for multiple LLM providers and vector stores. This Gmail MCP server was built as a learning exercise based on Rig's patterns and architecture.

✨ Features

• 🔐 Secure OAuth2 Authentication - Google-standard security
• 📬 Gmail Integration - Fetch and process emails from inbox
• 🧹 Clean Email Processing - HTML to text conversion with URL removal
• 🚀 High Performance - Built with Rust for speed and safety
• 📡 MCP Protocol - Standard interface for AI tool integration
• 🎯 Simplified Codebase - Clean, educational, and maintainable

🏗️ Architecture

This server implements the Model Context Protocol (MCP) to provide Gmail functionality:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│  Gmail MCP Server │◄──►│   Gmail API     │
│   (Claude, etc) │    │   (This Project)  │    │   (Google)      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🚀 Quick Start

Prerequisites

• Rust (1.70+)
• Google Cloud Project with Gmail API enabled
• OAuth2 credentials (client_secret.json)

Setup

1. Clone & Build

   git clone https://github.com/RustSandbox/gmail_MCP.git
   cd gmail_MCP
   cargo build --release
   

2. Configure Gmail API

   • Go to Google Cloud Console
   • Enable Gmail API
   • Create OAuth2 credentials
   • Download as client_secret.json in project root

3. Run Server

   cargo run
   

   Server starts on http://localhost:3003/sse

Usage

The server provides a single tool:

gmail_reader - Read Gmail emails

• action (string): Action to perform ("read")
• max_results (number, optional): Max emails to fetch (1-500, default: 10)

🔧 Configuration

Environment Setup

No environment variables needed! The server uses:

• client_secret.json - OAuth2 credentials (required)
• token_cache.json - Generated automatically after first auth

Authentication Flow

1. First run opens browser for Google OAuth2
2. Grant Gmail read permissions
3. Tokens cached for future use
4. Delete token_cache.json to re-authenticate

📊 Project Stats

• Total Lines: ~400 (highly simplified!)
• Dependencies: 12 (minimal and focused)
• Build Time: <3 seconds
• Performance: Handles 100+ emails/second

🧩 Code Structure

src/
├── main.rs          # MCP server setup and tool registration
├── lib.rs           # Gmail API integration and OAuth2 
├── reademail.rs     # Email processing and URL cleanup
└── Cargo.toml       # Dependencies and metadata

Clean Code Principles Applied:

• Single Responsibility - each module has one purpose
• DRY - no duplicate code
• KISS - simple, readable implementations
• Error Handling - comprehensive Result types

🛠️ Development

Testing

cargo test

Linting

cargo clippy

Formatting

cargo fmt

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Model Context Protocol - Official MCP documentation
• gmail1 - Gmail API client library
• mcp-core - MCP server implementation

🙏 Acknowledgments

• Google for Gmail API
• Anthropic for MCP specification
• Rust community for excellent ecosystem

Made with ❤️ and 🦀 Rust