Zoho Mail MCP
Integrates with Zoho Mail's API to let agents work with a Zoho Mail inbox: listing accounts and folders, listing/reading messages and threads, searching mail, sending and drafting emails, replying, organising messages across folders, and downloading attachments. Supports all Zoho data centers (com, in, eu, com.au, jp, sa, ca) and exposes 33 tools covering the accounts, folders, messages and threads endpoints, with optional settings such as a default sender address, a download directory for attachments, and an opt-in flag for permanent deletion (default keeps deletes recoverable in Trash).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Zoho Mail MCP find unread emails from my boss and summarize them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 andmail.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.
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.
In the self client's Generate Code tab, enter these scopes and generate a code:
ZohoMail.messages.ALL,ZohoMail.accounts.READ,ZohoMail.folders.READExchange the code for a refresh token within its validity window. Replace
zoho.comwith 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_tokenfrom the response. Using the wrong data center returnsinvalid_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 .envFill in .env, then run the read-only smoke test, which lists your folders and the latest inbox email:
npm run checkVariable | Notes |
| From Step 1 |
|
|
| Optional. Empty uses your default mail account. |
| Optional default sender. Empty uses the account's primary address. |
| Optional. Where attachments are saved. |
| Optional. |
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-mcpclaude plugin install velura-zoho-mail@veluralabsThe 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.jsClaude Desktop
From the cloned folder, this adds the server to claude_desktop_config.json and keeps a backup:
npm run install:claude -- desktopRestart 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 | |
|
|
|
|
Folders | |
|
|
|
|
Messages: read | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Messages: compose | |
|
|
|
|
|
|
|
|
Messages: update ( | |
| modes |
| mode |
| mode |
| mode |
| mode |
| modes |
|
|
Threads ( | |
| modes |
| mode |
| modes |
| modes |
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_emailswithstatus: "unread".Thread flags use names. Zoho's docs list
0-3for thread flags, but the API only acceptsinfo,important,followupandflag_not_set.Scheduled sending. Scheduled mail waits in the Outbox; deleting it there cancels it. For a custom time,
scheduleTimeis 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_emailandzoho_reply_to_emailsend 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.
Pay or donate: https://razorpay.me/@veluralabs
Contact: Dr Ishit Karoli, admin@veluralabs.com
Website: https://veluralabs.com
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 toolszoho_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_emailADestructive
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_accountARead-only
Get details of one mail account. Defaults to the configured account.
Inputs: accountId.
zoho_get_accountsBRead-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_infoBRead-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_contentBRead-only
Get the body (HTML) of an email.
Inputs: folderId (required), messageId (required), includeBlockContent.
zoho_get_email_headersBRead-only
Get the internet message headers of an email (Message-ID, References, Received, authentication results…).
Inputs: folderId (required), messageId (required), raw.
zoho_get_email_metadataBRead-only
Get metadata of an email (subject, sender, recipients, times, size, status, flag, attachment flags, summary).
Inputs: folderId (required), messageId (required).
zoho_get_folderCRead-only
Get details of a single folder.
Inputs: folderId (required).
zoho_get_original_messageBRead-only
Get the full original MIME source of an email (headers + all parts).
Inputs: messageId (required).
zoho_list_emailsARead-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_foldersARead-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_emailsARead-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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over 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
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseNot gradedqualityCmaintenanceConnects any IMAP/SMTP mailbox to AI agents via MCP, enabling email read, search, send, reply, and management through natural language.13 npmMIT
- FlicenseBqualityBmaintenanceEnables 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.303-
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT