Zoho Mail MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to Zoho Mail. Read, search, send, schedule, organize, and download mail through the official Zoho Mail REST API.

Tools

Related MCP server: Zoho Mail MCP

Setup

1. Create a Zoho API Client

1. Go to the Zoho API Console (use .com for US datacenter)

2. Click Add Client > Self Client

3. Note your Client ID and Client Secret

2. Generate a Refresh Token

Run the interactive setup helper:

bun run setup.ts

Or manually:

1. In the Self Client, generate a grant code with these scopes:

   ZohoMail.accounts.READ,ZohoMail.folders.ALL,ZohoMail.messages.ALL,ZohoMail.tags.ALL

2. Set duration to 10 minutes, add a description, and click Create

3. Copy the generated code and exchange it using the setup script

3. Verify Credentials

ZOHO_CLIENT_ID=your_id ZOHO_CLIENT_SECRET=your_secret ZOHO_REFRESH_TOKEN=your_token bun run setup.ts --verify

4. Configure Your MCP Client

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "zoho-mail": {
      "command": "bun",
      "args": ["run", "/path/to/zoho-mail-mcp/src/index.ts"],
      "env": {
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_DATACENTER": "eu"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "zoho-mail": {
      "command": "bun",
      "args": ["run", "/path/to/zoho-mail-mcp/src/index.ts"],
      "env": {
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_DATACENTER": "eu"
      }
    }
  }
}

Environment Variables

Features

• OAuth2 with serialized auto-refresh - concurrent requests share token refreshes

• Resilient HTTP client - timeouts, exponential retry, Retry-After, and structured Zoho errors

• Multi-datacenter and multi-account support - route to eight Zoho regions and select the mailbox explicitly

• Safe destructive operations - permanent deletion, folder emptying, and overwrites require confirmation

• Rich search - plain text, exact phrases, fields, folders, labels, dates, flags, attachments, and conversations

• Mailbox workflows - drafts, templates, scheduling, reply-all, attachments, labels, folders, and bulk updates

• HTML to plain text - email content is converted to clean plain text for AI consumption

Search behavior

search_emails translates normal text to Zoho's required search syntax. For example, quarterly report searches for both words across the entire message. Use exactPhrase=true for an exact phrase, select a field such as subject or sender, or pass a complete expression such as subject:Invoice::has:attachment with rawSyntax=true.

Development

bun install
bun run typecheck
bun test

Requirements

• Bun runtime

• A Zoho Mail account with API access

License

MIT