# Zoho Mail MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating with Zoho Mail API, providing seamless email management, organization administration, and productivity features through AI assistants like Claude.

## 🚀 Features

### Core Email Functions
- **Send & Receive**: Send emails with/without attachments, list and search emails
- **Email Management**: Mark as read/unread, move between folders, delete emails
- **Content Access**: Get full email content and manage email threads

### Organization Management
- **Domain Management**: Add, verify, and manage domains with DNS settings
- **User Administration**: Add users, manage permissions and storage limits
- **Security**: IP allowlists, spam management, and audit logging

### Productivity Tools
- **Folders & Labels**: Create and organize email folders and labels
- **Tasks**: Manage group and personal tasks
- **Bookmarks**: Save and organize important links
- **Notes**: Create and manage notes within groups

### Advanced Features
- **Multi-region Support**: Automatically adapts to different Zoho regions (.com, .in, .eu, etc.)
- **Structured Responses**: All API responses are structured with consistent error handling
- **Comprehensive Logging**: Detailed logging for debugging and monitoring

## 📋 Prerequisites

- Python 3.8 or higher
- Nango account with Zoho Mail integration configured
- Zoho Mail account with appropriate permissions

## 🛠️ Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd zoho-mail-mcp-server
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Set up environment variables**
   Create a `.env` file in the project root:
   ```env
   NANGO_CONNECTION_ID=your_connection_id
   NANGO_INTEGRATION_ID=your_integration_id
   NANGO_BASE_URL=https://api.nango.dev
   NANGO_SECRET_KEY=your_nango_secret_key
   ```

## ⚙️ Configuration

### Nango Setup

1. **Create a Nango Account**
   - Visit [Nango](https://nango.dev) and create an account
   - Set up a new integration for Zoho Mail

2. **Configure Zoho Mail Integration**
   - In Nango dashboard, create a new Zoho Mail integration
   - Configure the required scopes:
     - `ZohoMail.messages.ALL`
     - `ZohoMail.folders.ALL`
     - `ZohoMail.accounts.READ`
     - `ZohoMail.organization.ALL` (for admin functions)

3. **Get Connection Details**
   - Create a connection in Nango
   - Note down your connection ID, integration ID, and secret key
   - Ensure your connection config includes the correct extension (e.g., `{'extension': 'in'}`)

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `NANGO_CONNECTION_ID` | Your Nango connection identifier | ✅ |
| `NANGO_INTEGRATION_ID` | Your Nango integration identifier | ✅ |
| `NANGO_BASE_URL` | Nango API base URL | ✅ |
| `NANGO_SECRET_KEY` | Your Nango secret key | ✅ |

## 🚀 Usage

### Starting the Server

```bash
python zoho_mail_mcp.py
```

The server will start and automatically detect your Zoho region based on your Nango configuration.

### Using with Claude Desktop

1. **Add to Claude Desktop Configuration**
   
   Edit your Claude Desktop config file (usually located at `~/.claude/claude_desktop_config.json`):

   ```json
   {
     "mcpServers": {
       "zoho-mail": {
         "command": "python",
         "args": ["/path/to/your/zoho_mail_mcp.py"],
         "env": {
           "NANGO_CONNECTION_ID": "your_connection_id",
           "NANGO_INTEGRATION_ID": "your_integration_id", 
           "NANGO_BASE_URL": "https://api.nango.dev",
           "NANGO_SECRET_KEY": "your_nango_secret_key"
         }
       }
     }
   }
   ```

2. **Restart Claude Desktop**

3. **Start Using**
   
   You can now use natural language commands with Claude:
   
   ```
   "Send an email to john@example.com with subject 'Meeting Tomorrow'"
   "List my recent emails"
   "Create a new folder called 'Projects'"
   "Show me all users in my organization"
   ```

## 📚 Available Functions

### Authentication
- `get_nango_auth_info()` - Get current authentication status and user info

### Email Management
- `send_email()` - Send email with basic options
- `send_email_with_attachments()` - Send email with file attachments
- `list_emails()` - List emails in account or specific folder
- `search_emails()` - Search emails with custom parameters
- `get_email_content()` - Get full email content
- `mark_emails_as_read()` / `mark_emails_as_unread()` - Change read status
- `move_emails()` - Move emails between folders
- `delete_email()` - Delete specific email

### Folder & Label Management
- `create_folder()` / `delete_folder()` - Manage email folders
- `get_all_folders()` / `get_folder_details()` - Retrieve folder information
- `create_label()` / `update_label()` / `delete_label()` - Manage email labels

### Organization Management
- `get_organization_details()` - Get organization information
- `add_domain()` / `verify_domain()` - Domain management
- `add_user()` / `get_all_users()` - User administration
- `create_group()` / `get_all_groups()` - Group management

### Security & Compliance
- `add_allowed_ips()` / `get_allowed_ips()` - IP allowlist management
- `get_login_history()` - Access login audit logs
- `get_audit_records()` - Get detailed audit records

### Productivity Tools
- `add_task()` / `get_all_tasks_in_group()` - Task management
- `create_bookmark()` / `get_all_bookmarks()` - Bookmark management
- `create_note()` / `edit_note()` - Note management

## 🌍 Multi-Region Support

The server automatically detects your Zoho region from Nango configuration:

- **Global (.com)**: `https://mail.zoho.com/api`
- **India (.in)**: `https://mail.zoho.in/api`
- **Europe (.eu)**: `https://mail.zoho.eu/api`
- **China (.com.cn)**: `https://mail.zoho.com.cn/api`

No manual configuration needed - the server adapts automatically!

## 🔧 Troubleshooting

### Common Issues

**1. Authentication Errors**
```
Error: Authentication failed: No access token found
```
- Verify your Nango environment variables are correct
- Check that your Nango connection is active and not expired
- Ensure your Zoho Mail integration has the required scopes

**2. Wrong Region/Extension**
```
Error: HTTP 404: Not Found
```
- Check your Nango connection config includes the correct extension
- Verify you're using the right Zoho region for your account

**3. Permission Errors**
```
Error: HTTP 403: Forbidden
```
- Ensure your Zoho account has the necessary permissions
- For organization functions, you need admin privileges
- Check that required scopes are granted in Nango

### Debug Mode

Enable detailed logging by setting the log level:

```python
logging.basicConfig(level=logging.DEBUG)
```

### Testing Connection

Use the authentication info function to test your setup:

```python
# This will show your current auth status
auth_info = get_nango_auth_info()
print(f"Connected as: {auth_info.user_email}")
print(f"Region: {auth_info.extension}")
print(f"Scopes: {auth_info.scopes}")
```

## 📖 API Response Format

All functions return structured `ApiResponse` objects:

```python
{
    "success": bool,           # Whether operation succeeded
    "data": dict,             # Response data from Zoho API
    "error": str,             # Error message if any
    "status_code": int        # HTTP status code
}
```

## 🤝 Contributing

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Issues**: Open an issue on GitHub for bugs or feature requests
- **Documentation**: Check the [Zoho Mail API Documentation](https://www.zoho.com/mail/help/api/)
- **Nango Help**: Visit [Nango Documentation](https://docs.nango.dev/) for authentication issues

## 🏗️ Roadmap

- [ ] Real-time email notifications via webhooks
- [ ] Email template management
- [ ] Advanced search filters
- [ ] Bulk operations support
- [ ] Calendar integration
- [ ] Mobile push notifications setup

---

**Made with ❤️ for seamless Zoho Mail integration**