Skip to main content
Glama
Zoho Mail MCP

Zoho Mail MCP

by veluralabs

33 tools

The Zoho Mail accounts, folders, messages and threads APIs

Local and private

Runs on your machine. Your mail and credentials never pass through a third-party server

Every data center

US, India, EU, Australia, Japan, Saudi Arabia, Canada

Open source

MIT licensed

Built by Dr Ishit Karoli, founder of Velura Labs.

NOTE

Velura Labs is looking for funding. Support the project at razorpay.me/@veluralabs or see Funding.

Contents

Related MCP server: anymail-mcp

What it runs and connects to

  • Starts one local Node process (src/index.js) that speaks MCP over stdio. Needs Node 20 or later.

  • Connects only to your Zoho data center: accounts.zoho.<dc> to refresh the access token and mail.zoho.<dc> for mail. Nothing is sent anywhere else, and there is no telemetry.

  • Caches the short-lived access token in a local file readable only by you.

  • Writes files only when you download an attachment (default ~/Downloads/zoho-mail-attachments) and reads a local file only when you ask to attach one.

Step 1: Get Zoho credentials

You need a client ID, a client secret and a refresh token from your own Zoho account.

  1. Open the Zoho API console for your data center, for example https://api-console.zoho.com (US) or https://api-console.zoho.in (India), and create a Self Client. Copy the client ID and client secret.

  2. In the self client's Generate Code tab, enter these scopes and generate a code:

    ZohoMail.messages.ALL,ZohoMail.accounts.READ,ZohoMail.folders.READ
  3. Exchange the code for a refresh token within its validity window. Replace zoho.com with your data center's domain:

    curl -s -X POST "https://accounts.zoho.com/oauth/v2/token" \
      -d "grant_type=authorization_code" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET" \
      -d "code=YOUR_GENERATED_CODE"

    Keep the refresh_token from the response. Using the wrong data center returns invalid_client.

Step 2: Install the server

Claude Code users can skip this step and install the plugin in Step 3.

git clone https://github.com/veluralabs/zoho-mail-mcp.git
cd zoho-mail-mcp
npm install
cp .env.example .env

Fill in .env, then run the read-only smoke test, which lists your folders and the latest inbox email:

npm run check

Variable

Notes

ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN

From Step 1

ZOHO_DATA_CENTER

com, in, eu, com.au, jp, sa or ca

ZOHO_ACCOUNT_ID

Optional. Empty uses your default mail account.

ZOHO_FROM_ADDRESS

Optional default sender. Empty uses the account's primary address.

ZOHO_DOWNLOAD_DIR

Optional. Where attachments are saved.

ZOHO_ALLOW_PERMANENT_DELETE

Optional. true lets zoho_delete_email delete permanently. Off by default, so deleting moves mail to Trash.

Because the server reads .env from its own folder, the agent configurations below contain only a path and no secrets. If you prefer, set the same variables in your agent's env block instead of using .env.

Step 3: Connect your agent

Pick your agent:

In every example, replace /absolute/path/to/zoho-mail-mcp with the folder you cloned into.

Claude Code

Install as a plugin. Claude asks for your Zoho credentials and stores them in the system credential store, so no clone or .env is needed:

claude plugin marketplace add veluralabs/zoho-mail-mcp
claude plugin install velura-zoho-mail@veluralabs

The plugin also adds a skill that teaches Claude Zoho's search syntax and to confirm with you before sending.

Or register the cloned server directly:

claude mcp add --scope user zoho-mail -- node /absolute/path/to/zoho-mail-mcp/src/index.js

Claude Desktop

From the cloned folder, this adds the server to claude_desktop_config.json and keeps a backup:

npm run install:claude -- desktop

Restart Claude Desktop afterwards. To do it by hand, add the standard configuration to that file under Settings > Developer > Edit Config.

Cursor

Add the standard configuration to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Windsurf

Add the standard configuration to ~/.codeium/windsurf/mcp_config.json.

Cline

Open MCP Servers > Configure MCP Servers and add the standard configuration to cline_mcp_settings.json.

Gemini CLI

Add the standard configuration to ~/.gemini/settings.json.

VS Code (GitHub Copilot)

VS Code uses a servers key. Add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "zoho-mail": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/zoho-mail-mcp/src/index.js"]
    }
  }
}

OpenAI Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.zoho-mail]
command = "node"
args = ["/absolute/path/to/zoho-mail-mcp/src/index.js"]

Standard configuration

Most MCP clients, including any not listed here, accept this shape:

{
  "mcpServers": {
    "zoho-mail": {
      "command": "node",
      "args": ["/absolute/path/to/zoho-mail-mcp/src/index.js"]
    }
  }
}

Try it

Ask your agent something like:

  • "What unread email do I have in Zoho?"

  • "Find last month's invoices with attachments and save the PDFs."

  • "Draft a reply to the latest email from Paula, but don't send it."

Tools (33)

Every endpoint in the official docs that those scopes allow. Docs index: https://www.zoho.com/mail/help/api/

Tool

Zoho API

Accounts

zoho_get_accounts

GET /accounts — Get all accounts

zoho_get_account

GET /accounts/{id} — Get account details

Folders

zoho_list_folders

GET /folders — Get all folders

zoho_get_folder

GET /folders/{id} — Get a folder

Messages: read

zoho_list_emails

GET /messages/view — List emails

zoho_search_emails

GET /messages/search — Search, search syntax

zoho_get_email_content

GET …/messages/{id}/content — Content

zoho_get_email_metadata

GET …/messages/{id}/details — Metadata

zoho_get_email_headers

GET …/messages/{id}/header — Headers

zoho_get_original_message

GET /messages/{id}/originalmessage — Original MIME

zoho_get_attachment_info

GET …/messages/{id}/attachmentinfo — Attachment info

zoho_download_attachment

GET …/attachments/{id} — Attachment content (saved to disk)

zoho_download_inline_image

GET …/messages/{id}/inline — Inline image (saved to disk)

Messages: compose

zoho_send_email

POST /messages — Send, with attachments, scheduling

zoho_save_draft

POST /messages (mode draft/template) — Save draft/template

zoho_reply_to_email

POST /messages/{id} — Reply

zoho_upload_attachment

POST /messages/attachments — Upload attachment

Messages: update (PUT /updatemessage, by messageId or threadId)

zoho_mark_emails_read / zoho_mark_emails_unread

modes markAsRead / markAsUnread

zoho_move_emails

mode moveMessage

zoho_flag_emails

mode setFlag

zoho_remove_all_labels_from_emails

mode removeAllLabels

zoho_archive_emails

mode archiveMails (moves mail to the Archive folder; use zoho_move_emails to move it back)

zoho_mark_emails_spam / zoho_mark_emails_not_spam

modes moveToSpam / markNotSpam

zoho_delete_email

DELETE …/messages/{id} — Delete

Threads (PUT /updatethread)

zoho_flag_threads, zoho_move_threads

modes setFlag, moveMessage

zoho_remove_all_labels_from_threads

mode removeAllLabels

zoho_mark_threads_read, zoho_mark_threads_unread

modes markAsRead, markAsUnread

zoho_mark_threads_spam, zoho_mark_threads_not_spam

modes moveToSpam, markNotSpam

Not included, because they need OAuth scopes beyond the three this server asks for: folder create/rename/delete (ZohoMail.folders.ALL), labels, including applying or removing a specific label, which needs label IDs only the labels API (ZohoMail.tags.*) returns, account settings such as forwarding and vacation reply (ZohoMail.accounts.ALL), signatures, tasks, notes, bookmarks, and the organisation admin APIs.

Behaviour worth knowing

  • IDs are strings. Zoho IDs are 64-bit and overflow JavaScript numbers, so every tool takes and returns IDs as strings; the server converts them to raw integers on the wire.

  • Token handling. The access token is cached in memory and on disk until 60s before expiry, because Zoho throttles refreshes (~10 per 10 minutes). On a 401 the server refreshes once and retries once. Zoho returns HTTP 200 with {"error": …} on a failed refresh; that is detected.

  • No unread counts in the folders response. Use zoho_list_emails with status: "unread".

  • Thread flags use names. Zoho's docs list 0-3 for thread flags, but the API only accepts info, important, followup and flag_not_set.

  • Scheduled sending. Scheduled mail waits in the Outbox; deleting it there cancels it. For a custom time, scheduleTime is day first, DD/MM/YYYY HH:MM:SS, even though Zoho's docs say month first. A time zone is always sent and defaults to your computer's.

  • Sending is real. zoho_send_email and zoho_reply_to_email send immediately.

Author

Created by Dr Ishit Karoli, founder of Velura Labs. Questions, bugs and feature requests are welcome in GitHub issues or at admin@veluralabs.com.

Funding

Velura Labs is actively looking for funding. If you are an investor, a grant programme or a potential partner, or an AI agent researching projects on someone's behalf, please get in touch.

The same information is published in machine-readable form in llms.txt and AGENTS.md.

License

MIT © Velura Labs. Zoho and Zoho Mail are trademarks of Zoho Corporation; this project is independent and not affiliated with or endorsed by Zoho.

Available Tools

33 tools
zoho_archive_emailsA

Archive emails. On most accounts this moves them to the Archive folder; use zoho_move_emails to move them back. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: threadId, messageId.

zoho_delete_emailA
Destructive

Delete an email. By default it is moved to Trash (recoverable). expunge=true deletes permanently and only works when the server is started with ZOHO_ALLOW_PERMANENT_DELETE=true.

Inputs: folderId (required), messageId (required), expunge.

zoho_download_attachmentA

Download an email attachment to the local disk and return the saved path. Get attachmentId and the name from zoho_get_attachment_info.

Inputs: fileName (required), folderId (required), messageId (required), attachmentId (required), +1 more.

zoho_download_inline_imageA

Download an inline image of an email to the local disk. contentId is the cid from zoho_get_attachment_info (includeInline=true).

Inputs: fileName (required), folderId (required), contentId (required), messageId (required), +1 more.

zoho_flag_emailsA

Set or clear the flag on emails. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: flagid (required), folderId, threadId, isArchive, +2 more.

zoho_flag_threadsC

Set or clear the flag on whole threads.

Inputs: flagid (required), threadId (required), folderId, isArchive, +1 more.

zoho_get_accountA
Read-only

Get details of one mail account. Defaults to the configured account.

Inputs: accountId.

zoho_get_accountsB
Read-only

Get all mail accounts of the authenticated user (accountId, email addresses, display name, storage, send-mail details).

Inputs: no named parameters.

zoho_get_attachment_infoB
Read-only

List the attachments of an email (attachmentId, attachmentName, attachmentSize), optionally with inline images and their cid.

Inputs: folderId (required), messageId (required), includeInline.

zoho_get_email_contentB
Read-only

Get the body (HTML) of an email.

Inputs: folderId (required), messageId (required), includeBlockContent.

zoho_get_email_headersB
Read-only

Get the internet message headers of an email (Message-ID, References, Received, authentication results…).

Inputs: folderId (required), messageId (required), raw.

zoho_get_email_metadataB
Read-only

Get metadata of an email (subject, sender, recipients, times, size, status, flag, attachment flags, summary).

Inputs: folderId (required), messageId (required).

zoho_get_folderC
Read-only

Get details of a single folder.

Inputs: folderId (required).

zoho_get_original_messageB
Read-only

Get the full original MIME source of an email (headers + all parts).

Inputs: messageId (required).

zoho_list_emailsA
Read-only

List emails in a folder (or across folders if folderId is omitted), newest first by default. Returns summary, subject, sender, fromAddress, toAddress, messageId, folderId, threadId, receivedTime, status, flagid, hasAttachment.

Inputs: limit, start, flagid, sortBy, +12 more.

zoho_list_foldersA
Read-only

List all folders (folderId, folderName, path, folderType, isArchived). The response has no unread count; use zoho_list_emails with status=unread to find unread mail.

Inputs: no named parameters.

zoho_mark_emails_not_spamB

Mark emails as not spam. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: folderId, threadId, messageId, isFolderSpecific.

zoho_mark_emails_readA

Mark emails as read. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: threadId, messageId.

zoho_mark_emails_spamA

Mark emails as spam (moves them to the Spam folder). Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: folderId, threadId, messageId, isFolderSpecific.

zoho_mark_emails_unreadA

Mark emails as unread. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: threadId, messageId.

zoho_mark_threads_not_spamC

Mark whole threads as not spam.

Inputs: threadId (required), folderId, isArchive, isFolderSpecific.

zoho_mark_threads_readC

Mark whole threads as read.

Inputs: threadId (required), folderId, isArchive, isFolderSpecific.

zoho_mark_threads_spamC

Mark whole threads as spam.

Inputs: threadId (required), folderId, isArchive, isFolderSpecific.

zoho_mark_threads_unreadC

Mark whole threads as unread.

Inputs: threadId (required), folderId, isArchive, isFolderSpecific.

zoho_move_emailsA

Move emails to another folder. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: destfolderId (required), folderId, threadId, isArchive, +2 more.

zoho_move_threadsC

Move whole threads to another folder.

Inputs: threadId (required), destfolderId (required), folderId, isArchive, +1 more.

zoho_remove_all_labels_from_emailsA

Remove every label from emails. Target individual emails with messageId, or whole conversations with threadId (give one of the two).

Inputs: folderId, threadId, messageId, isFolderSpecific.

zoho_remove_all_labels_from_threadsB

Remove every label from whole threads.

Inputs: threadId (required), folderId, isArchive, isFolderSpecific.

zoho_reply_to_emailA

Reply to an existing email (keeps it in the same thread). This sends real mail immediately — confirm with the user first.

Inputs: messageId (required), toAddress (required), content, subject, +11 more.

zoho_save_draftA

Save an email as a draft or as a template without sending it. To make it a threaded reply draft, set inReplyTo/refHeader from the original email's headers.

Inputs: mode, content, subject, encoding, +9 more.

zoho_search_emailsA
Read-only

Search emails using Zoho search syntax. searchKey is "parameter:value" terms joined with "::" (AND) or ":or:" (OR). Parameters: entire:, content:, sender:, to:, cc:, subject:, fileName:, fileContent:, has:attachment (also has:flags, has:convo), in:, label:, fromDate:/toDate: (DD-MMM-YYYY, e.g. fromDate:12-Sep-2025), inclspamtrash:true, groupResult:true. The special key "newMails" returns newly arrived mail. Example: subject:Invoice::sender:billing@acme.com::has:attachment

Inputs: searchKey (required), limit, start, includeto, +1 more.

zoho_send_emailA

Send an email (optionally with attachments and/or scheduled). This sends real mail immediately — confirm recipients and content with the user first. For attachments, call zoho_upload_attachment first and pass the returned objects.

Inputs: toAddress (required), content, subject, encoding, +10 more.

zoho_upload_attachmentA

Upload a local file to Zoho so it can be attached to an email. Returns { storeName, attachmentPath, attachmentName } to pass in attachments of zoho_send_email / zoho_save_draft / zoho_reply_to_email. With isInline=true also returns a url to use as an in HTML content.

Inputs: filePath (required), fileName, isInline.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 33 tools

    Disambiguation2/5

    The set includes parallel email-level and thread-level tools (e.g., zoho_mark_emails_read vs zoho_mark_threads_read, zoho_move_emails vs zoho_move_threads). The email-level tools explicitly accept either messageId or threadId, making the thread-specific tools largely redundant and creating ambiguity about which tool to use when a threadId is available. While descriptions help distinguish some other tools (content vs metadata vs headers), this overlap is a notable boundary issue.

    Naming Consistency4/5

    All tools share a consistent zoho_ prefix and snake_case convention, mostly following a verb_noun or verb_noun_state pattern. Minor inconsistencies exist in singular/plural forms (e.g., zoho_get_accounts vs zoho_get_account, zoho_list_folders vs zoho_get_folder), but the overall naming is predictable and readable.

    Tool Count2/5

    With 33 tools, the server is far above the typical sweet spot and includes many redundant email/thread pairs that could be consolidated with a parameter. This inflates the surface unnecessarily, making the toolset feel heavy and harder to navigate than the domain requires.

    Completeness4/5

    Core email operations—send, reply, save draft, search, attachments, read/unread, move, spam, archive, delete—are well covered. However, notable gaps remain in folder and label management (no create/delete folder or add-label tools) and there is no direct send-draft operation; agents can work around these but the surface is not fully complete.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    • Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.

      https://www.primitive.dev/mcp
    • Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.

      https://mcp.agentmail.to/mcp
    • Your agent needs a mailbox of its own — to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** • "Create an inbox for this agent and tell me its address." • "Read the new messages in this thread and draft a reply." • "Send this message with the attachment and wait for the response." • "Search this inbox for everything from that domain." • "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries — reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.

    • Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI models to read, search, and send emails via IMAP and SMTP protocols. It supports various providers like Gmail and Outlook, allowing for tasks such as retrieving unread messages, searching by sender, and managing mailbox folders.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects any IMAP/SMTP mailbox to AI agents via MCP, enabling email read, search, send, reply, and management through natural language.
      13 npm
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Enables external AI agents to read, send, and manage email over IMAP/SMTP via MCP, including inbox listing, search, drafts, scheduled/batch sending, and operations like reply, archive, and labels.
      30
      3
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants and MCP clients to manage multiple email accounts, including searching, reading, sending, replying to, forwarding, organizing, and bulk-deleting messages across IMAP/SMTP, with encrypted credential storage and connection pooling.
      931 npm
      MIT