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

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

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 (default profile; *or provide per-mailbox tokens)
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 (single-mailbox mode)
ZOHO_ACCOUNT_EMAIL	No	Select an account by primary address or alias (single-mailbox mode)
ZOHO_DEFAULT_MAILBOX	No	Default profile name when tools omit mailbox
ZOHO_MAILBOXES	No	Multi-mailbox JSON array or comma list of names (see below)
ZOHO_MAILBOX_<NAME>_REFRESH_TOKEN	No	Per-profile refresh token (e.g. ZOHO_MAILBOX_IMMA_REFRESH_TOKEN)
ZOHO_MAILBOX_<NAME>_EMAIL	No	Prefer this address within the profile
ZOHO_MAILBOX_<NAME>_ACCOUNT_ID	No	Prefer this accountId within the profile
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

Multi-mailbox (fork)

Zoho mailbox delegation ("Delegated to me" in the web UI) does not expose the other user's messages through OAuth. Each person needs their own refresh token, minted while logged into Zoho as that user (same Self Client + scopes is fine).

JSON form:

ZOHO_DEFAULT_MAILBOX=agusti
ZOHO_MAILBOXES='[
  {"name":"agusti","refreshToken":"1000.…","email":"agusti@cruceritis.com"},
  {"name":"imma","refreshToken":"1000.…","email":"imma@cruceritis.com"}
]'

Or env discovery:

ZOHO_REFRESH_TOKEN=1000.…agusti…          # fallback / primary
ZOHO_DEFAULT_MAILBOX=agusti
ZOHO_MAILBOX_AGUSTI_REFRESH_TOKEN=1000.…  # optional if same as ZOHO_REFRESH_TOKEN
ZOHO_MAILBOX_AGUSTI_EMAIL=agusti@cruceritis.com
ZOHO_MAILBOX_IMMA_REFRESH_TOKEN=1000.…    # mint as Imma
ZOHO_MAILBOX_IMMA_EMAIL=imma@cruceritis.com

Tools accept optional mailbox (e.g. search_emails with mailbox: "imma").

Mint a second token (Imma)

1. Log into Zoho as Imma (or use a browser profile already as her).
2. API Console → same Self Client → Generate Code with the same scopes.
3. Exchange the code for a refresh token (bun run setup.ts or curl).
4. Put that token in ZOHO_MAILBOX_IMMA_REFRESH_TOKEN (or the JSON entry).
5. Restart the MCP server / Grok session.

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