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

Clone the repository

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

Install dependencies

   pip install -r requirements.txt

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

Create a Nango Account

Visit Nango and create an account
Set up a new integration for Zoho Mail

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)

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

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

Restart Claude Desktop

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Zoho Mail MCP Server