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
| Tool | Description |
|---|---|
list_accounts |
Inspect accessible accounts and the selected account |
list_folders |
List mail folders with unread/total counts |
manage_folder |
Create, rename, move, mark read, empty, or delete folders |
list_labels |
List labels with colors and IDs |
manage_label |
Create, update, or delete labels |
list_emails |
List emails with rich filtering, sorting, and pagination |
read_email |
Read the full content of a specific email |
search_emails |
Search with plain text or Zoho's advanced syntax |
send_email |
Send or schedule email with receipts and attachments |
save_draft |
Save a draft or template, including reply threading |
reply_email |
Reply or reply-all immediately or on a schedule |
update_emails |
Bulk read, move, flag, label, archive, and spam actions |
list_attachments |
List attachment names, sizes, and IDs |
download_attachment |
Safely download an attachment locally |
delete_email |
Trash or permanently delete with explicit confirmation |
Setup
1. Create a Zoho API Client
- Go to the Zoho API Console (use
.comfor US datacenter) - Click Add Client > Self Client
- Note your Client ID and Client Secret
2. Generate a Refresh Token
Run the interactive setup helper:```bash
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```bash
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)```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`)```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
| Variable | Required | Description |
|---|---|---|
ZOHO_CLIENT_ID |
Yes | OAuth2 Client ID from Zoho API Console |
ZOHO_CLIENT_SECRET |
Yes | OAuth2 Client Secret |
ZOHO_REFRESH_TOKEN |
Yes | OAuth2 Refresh Token (generated via setup) |
ZOHO_DATACENTER |
No | Zoho datacenter: eu (default), us, in, au, jp, ca, sa, or uk |
ZOHO_ACCOUNT_ID |
No | Select a specific accessible account ID |
ZOHO_ACCOUNT_EMAIL |
No | Select an account by primary address or alias |
ZOHO_REQUEST_TIMEOUT_MS |
No | Per-request timeout; defaults to 30000 |
ZOHO_MAX_RETRIES |
No | Network/429/5xx retries; defaults to 3 |
ZOHO_RATE_LIMIT_PER_MINUTE |
No | Local request throttle; defaults to 30 |
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```bash
bun install
bun run typecheck
bun test
```
Requirements
- Bun runtime
- A Zoho Mail account with API access
License
MIT
