Content
# 🎯 InboxAI
AI-powered Gmail inbox organizer using LangGraph, LangChain, and Google's Gemini AI. Automatically classify, summarize, and manage your emails with intelligent workflows.
## 🌟 Features
- **Intelligent Email Classification**: Automatically categorizes emails into:
- 📰 **Informative** (newsletters, updates, notifications)
- 💬 **Requires Reply** (emails needing your response)
- 🗑️ **Ignored** (spam, promotions, unimportant messages)
- **AI-Powered Summarization**:
- Concise summaries of informative emails
- Context extraction for emails requiring replies
- Smart reply generation with multiple tone options
- **LangGraph Workflow**: State-machine orchestrated email processing pipeline
- **Model Context Protocol (MCP) Server**: Ready-to-use MCP server for AI assistant integration with Claude Desktop and other AI assistants
- **Gmail API Integration**: Full read/write access to your Gmail account
## 🏗️ Architecture
```
📧 InboxAI Workflow
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Fetch Emails │───▶│ Classify Emails │───▶│ Summarize │
│ │ │ │ │ Informative │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Summarize │───▶│ Present to │
│ Requires Reply │ │ User │
└─────────────────┘ └─────────────────┘
```
### 🔧 Project Structure
```
InboxAI/
├── src/
│ ├── main.py # CLI interface and main entry point
│ ├── mcp_server.py # Model Context Protocol server
│ ├── graph.py # LangGraph workflow definition
│ └── tools/
│ ├── gmail.py # Gmail API client and Email class
│ ├── summarise_email.py # Email summarization functions
│ └── reply_email.py # Email reply generation and sending
├── tests/
│ └── test_graph.py # Comprehensive test suite
├── pyproject.toml # Project configuration and dependencies
├── requirements.txt # Legacy requirements file
└── README.md # This file
```
## 🚀 Quick Start
### 1. Prerequisites
- Python 3.12+
- Gmail account with API access
- Google Cloud Project with Gmail API enabled
### 2. Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/InboxAI.git
cd InboxAI
# Install dependencies with uv (recommended)
uv sync
# Or install with pip
pip install -e .
```
### 3. Gmail API Setup
1. **Create a Google Cloud Project**:
- Go to [Google Cloud Console](https://console.cloud.google.com/)
- Create a new project or select existing one
2. **Enable Gmail API**:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API" and enable it
3. **Create Credentials**:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth 2.0 Client IDs"
- Choose "Desktop Application"
- Download the JSON file as `credentials.json`
4. **Place Credentials**:
```bash
# Place the downloaded file in the project root
cp ~/Downloads/credentials.json ./credentials.json
```
### 4. Environment Setup
Create a `.env` file in the project root:
```env
# Google AI API Key (for Gemini)
GOOGLE_API_KEY=your_google_ai_api_key_here
# Optional: Customize LLM model
LLM_MODEL=google_genai:gemini-2.5-flash
```
### 5. First Run
```bash
# Run InboxAI
uv run python src/main.py
# Or specify time window
uv run python src/main.py --time 7d
# Interactive mode
uv run python src/main.py --interactive
```
## 📖 Usage
### Command Line Interface
```bash
# Basic usage - process last 24 hours
uv run python src/main.py
# Specify time window
uv run python src/main.py --time 12h # Last 12 hours
uv run python src/main.py --time 7d # Last 7 days
uv run python src/main.py --time 3d # Last 3 days
# Show processing statistics
uv run python src/main.py --stats --time 24h
# Reply to an email
uv run python src/main.py --reply email_id_123 --reply-text "Thanks for your message!"
# Generate reply suggestions
uv run python src/main.py --suggestions email_id_123
# Interactive mode
uv run python src/main.py --interactive
```
### Interactive Mode Commands
```
📧 InboxAI> process 24h # Process emails from last 24 hours
📧 InboxAI> stats 7d # Show statistics for last 7 days
📧 InboxAI> reply 123 Thank you! # Reply to email with ID 123
📧 InboxAI> suggest 123 # Get reply suggestions for email 123
📧 InboxAI> quit # Exit interactive mode
```
### Python API
```python
from src.graph import process_inbox
from src.tools.reply_email import reply_to_email_mcp
from src.tools.summarise_email import summarise_emails_mcp
# Process emails
result = process_inbox("24h")
print(result)
# Summarize emails using MCP function
summary = summarise_emails_mcp("24h")
print(summary)
# Reply to an email
reply_result = reply_to_email_mcp(
email_id="123",
reply_text="Thank you for your email!",
auto_generate=False
)
# Auto-generate a reply
auto_reply = reply_to_email_mcp(
email_id="123",
auto_generate=True,
tone="professional"
)
```
## 🔧 Configuration
### Environment Variables
| Variable | Description | Default |
| ---------------- | ---------------------------- | ------------------------------- |
| `GOOGLE_API_KEY` | Google AI API key for Gemini | Required |
| `LLM_MODEL` | Language model to use | `google_genai:gemini-2.5-flash` |
### Gmail API Scopes
The application requires these Gmail API scopes:
- `https://www.googleapis.com/auth/gmail.readonly` - Read emails
- `https://www.googleapis.com/auth/gmail.send` - Send emails
- `https://www.googleapis.com/auth/gmail.modify` - Modify emails
## 🧪 Testing
Run the test suite:
```bash
# Install test dependencies
uv add --dev pytest pytest-mock
# Run tests
uv run pytest tests/ -v
# Run with coverage
uv run pytest tests/ --cov=src --cov-report=html
```
### Test Structure
- **Unit Tests**: Individual component testing
- **Integration Tests**: Complete workflow testing
- **Mock Tests**: Gmail API and LLM interaction testing
- **Error Handling**: Exception and edge case testing
## 🔌 MCP Integration
InboxAI provides a Model Context Protocol server for integration with AI assistants like Claude Desktop:
### Available Tools
- `summarise_emails_mcp(time_window)` - Fetch and categorize emails with AI summaries
- `reply_to_email_mcp(email_id, reply_text)` - Send intelligent replies
- `get_email_suggestions(email_id, num_suggestions)` - Generate multiple reply options
- `process_inbox_full(time_window)` - Run complete workflow
### Usage with Claude Desktop
```bash
# Start MCP server
uv run python src/mcp_server.py
```
See [MCP_GUIDE.md](./MCP_GUIDE.md) for detailed integration instructions.
## 🎨 Customization
### Adding New Email Categories
1. Update the `EmailClassification` model in `graph.py`:
```python
category: Literal["informative", "requires_reply", "ignored", "urgent"] = Field(...)
```
2. Modify classification logic in `classify_emails_node()`
3. Add corresponding summarization logic
### Custom LLM Models
```python
# In graph.py, change the LLM initialization
llm = init_chat_model("openai:gpt-4") # Use OpenAI
llm = init_chat_model("anthropic:claude-3") # Use Anthropic
```
## 🐛 Troubleshooting
### Common Issues
1. **"Import googleapiclient.discovery could not be resolved"**
```bash
uv add google-api-python-client google-auth-oauthlib
```
2. **Gmail API Authentication Failed**
- Ensure `credentials.json` is in the correct location
- Check that Gmail API is enabled in Google Cloud Console
- Verify OAuth 2.0 client ID is configured for "Desktop Application"
3. **"No module named 'google.generativeai'"**
```bash
uv add google-generativeai
```
4. **Empty Email Results**
- Check Gmail API quotas and limits
- Verify time window format (e.g., "24h", "7d")
- Ensure you have unread emails in the specified timeframe
### Debug Mode
Enable detailed logging:
```bash
export PYTHONPATH=$PYTHONPATH:./src
uv run python src/main.py --time 1h --verbose
```
## 🚧 Development
### Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes and add tests
4. Run tests: `uv run pytest tests/`
5. Submit a pull request
### Development Setup
```bash
# Install development dependencies
uv sync --dev
# Install pre-commit hooks (optional)
pre-commit install
# Run linting
uv run flake8 src/ tests/
uv run black src/ tests/
# Type checking
uv run mypy src/
```
## 🏗️ Technical Architecture
### LangGraph State Machine
The email processing workflow is implemented as a LangGraph state machine with the following nodes:
- **Fetch Node**: Retrieves emails from Gmail API with time filtering
- **Classify Node**: Uses Gemini AI to categorize emails into types
- **Summarize Informative Node**: Generates concise summaries for informative emails
- **Summarize Reply Node**: Extracts context and suggests replies for actionable emails
- **Present Node**: Formats and presents results to the user
### AI Integration
- **Classification**: Uses structured output with Pydantic models for reliable categorization
- **Summarization**: Context-aware prompts optimized for different email types
- **Reply Generation**: Multi-tone reply suggestions with professional/casual/friendly options
### Data Privacy
- All email processing happens locally
- Only email classification/summarization uses external AI API (Google Gemini)
- No email content is stored permanently
- OAuth credentials are securely managed
## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 🙏 Acknowledgments
- **LangChain** & **LangGraph** for the orchestration framework
- **Google Gemini** for AI capabilities
- **Gmail API** for email access
- **Python ecosystem** for excellent tooling
## 📞 Support
- 📖 [Documentation](./README.md)
- 🔧 [Setup Guide](./SETUP.md)
- 🔌 [MCP Integration](./MCP_GUIDE.md)
- 🐛 [Issue Tracker](https://github.com/yourusername/InboxAI/issues)
---
**Built with ❤️ using LangGraph, LangChain, and Google AI**
_Designed for developers who want to leverage AI for intelligent email management._
Connection Info
You Might Also Like
awesome-mcp-servers
A collection of MCP servers.
git
A Model Context Protocol server for Git automation and interaction.
Appwrite
Build like a team of hundreds
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.
oh-my-opencode
Background agents · Curated agents like oracle, librarians, frontend...
chatbox
User-friendly Desktop Client App for AI Models/LLMs (GPT, Claude, Gemini, Ollama...)