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
-
Clone & Build
git clone https://github.com/RustSandbox/gmail_MCP.git cd gmail_MCP cargo build --release -
Configure Gmail API
- Go to Google Cloud Console
- Enable Gmail API
- Create OAuth2 credentials
- Download as
client_secret.jsonin project root
-
Run Server
cargo runServer 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
- First run opens browser for Google OAuth2
- Grant Gmail read permissions
- Tokens cached for future use
- Delete
token_cache.jsonto 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
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - 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
