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: io.github.p-w-4-z/inbox-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

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