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

   git clone <repository-url>
   cd zoho-mail-mcp-server
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Set up environment variables Create a .env file in the project root:

   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 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

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):

   {
     "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:

logging.basicConfig(level=logging.DEBUG)

Testing Connection

Use the authentication info function to test your setup:

# 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:

{
    "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 file for details.

🆘 Support

• Issues: Open an issue on GitHub for bugs or feature requests
• Documentation: Check the Zoho Mail API Documentation
• Nango Help: Visit Nango Documentation 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