ZeptoMail Templates MCP
Manages ZeptoMail email templates across all agents in a Zoho account, providing tools to list agents, list/search/read/create/update/delete templates, with support for read-only mode, agent allowlisting, and OAuth-based authentication.
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., "@ZeptoMail Templates MCP list all email templates in the production agent"
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.
ZeptoMail Templates MCP
An MCP server that lets an AI agent (opencode, Claude Desktop, Cursor, ...) inspect and manage email templates across all ZeptoMail Agents in your Zoho account.
It intentionally does not send email, create/delete Agents, expose Send Mail Tokens, or manage domains. It only reads the Agent list and manages templates.
Quickstart (local, ~5 minutes)
1. Install the server
npm i -g zeptomail-mcpThis gives you a zeptomail-mcp command on your PATH. Skip this if you'd rather run from a local clone of the repo (node /path/to/zeptomail-mcp/dist/src/server.js).
2. Create a Zoho OAuth app
Open the Zoho API Console.
Create a Server-based Application:
Client name:
zeptomailmcp(no hyphens — Zoho rejects them)Homepage URL: anything, e.g.
https://github.com/P4rthPat3l/zeptomail-mcpAuthorized redirect URI:
http://localhost:4567/callback
Note the Client ID and Client Secret.
A Self Client also works. It has no redirect URI field, so instead of step 2 use its Generate Code tab (see Self Client setup below).
3. Get a refresh token
ZOHO_CLIENT_ID=<your-client-id> ZOHO_CLIENT_SECRET=<your-secret> zeptomail-mcp-loginYour browser opens Zoho's consent screen for scopes Zeptomail.MailAgents.READ + Zeptomail.MailTemplates.All. After you approve, the script prints a refresh token.
If you're running from a local clone instead of a global install, this same command is
npm run login.
4. Configure your MCP host
You can pass the Zoho credentials inline in the host config, or load them from a .env file so the config file itself stays secret-free. Both work; pick one.
Option A — load from a .env file (recommended)
Put the secrets in a .env file (gitignore it — it's a credential):
# .env
ZOHO_CLIENT_ID=<your-client-id>
ZOHO_CLIENT_SECRET=<your-secret>
ZOHO_REFRESH_TOKEN=<your-refresh-token>
ZOHO_ACCOUNTS_URL=https://accounts.zoho.comThen point the server at it with --env-file. The path is resolved relative to the host's working directory; use an absolute path if unsure.
opencode — opencode.json (or .opencode/opencode.json):
{
"mcp": {
"zeptomail": {
"type": "local",
"command": ["zeptomail-mcp", "--env-file=/absolute/path/to/.env"],
"enabled": true
}
}
}Claude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"zeptomail": {
"command": "zeptomail-mcp",
"args": ["--env-file=/absolute/path/to/.env"]
}
}
}Option B — inline in the host config
opencode — opencode.json (or .opencode/opencode.json):
{
"mcp": {
"zeptomail": {
"type": "local",
"command": ["zeptomail-mcp"],
"enabled": true,
"environment": {
"ZOHO_CLIENT_ID": "...",
"ZOHO_CLIENT_SECRET": "...",
"ZOHO_REFRESH_TOKEN": "...",
"ZOHO_ACCOUNTS_URL": "https://accounts.zoho.com"
}
}
}
}Claude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"zeptomail": {
"command": "zeptomail-mcp",
"env": {
"ZOHO_CLIENT_ID": "...",
"ZOHO_CLIENT_SECRET": "...",
"ZOHO_REFRESH_TOKEN": "...",
"ZOHO_ACCOUNTS_URL": "https://accounts.zoho.com"
}
}
}
}Running from a local clone instead of a global install
Run the built launcher directly with node. It parses --env-file the same way the global zeptomail-mcp command does, so the flag goes after the script:
opencode (Option A env-file):
["node", "/absolute/path/to/zeptomail-mcp/dist/src/cli.js", "--env-file=/absolute/path/to/.env"]opencode (Option B inline):
["node", "/absolute/path/to/zeptomail-mcp/dist/src/cli.js"]+ theenvironmentblockClaude Desktop:
"command": "node","args": [".../dist/src/cli.js", "--env-file=..."](or just[".../dist/src/cli.js"]with theenvblock)
5. Use it
Ask your agent to call the tools:
"list my ZeptoMail agents"
"find the template with alias
team_invite""show me the OTP template in the sandbox agent"
Related MCP server: mcp-imap
Self Client setup
A Self Client has no redirect URI, so zeptomail-mcp-login cannot catch its callback. Instead:
API Console → Self Client → Generate Code.
Scope:
Zeptomail.MailAgents.READ,Zeptomail.MailTemplates.All→ CREATE.Copy the generated code and exchange it:
curl -X POST https://accounts.zoho.com/oauth/v2/token \
-d "code=<generated code>" \
-d "client_id=<client id>" \
-d "client_secret=<client secret>" \
-d "grant_type=authorization_code" \
-d "redirect_uri=https://api-console.zoho.com/"The JSON response contains refresh_token.
Tools
MCP tool | Purpose | Mutates data |
| List accessible Agents and exact Agent keys/aliases | No |
| List templates in one explicit Agent | No |
| Search one Agent or all Agents by name/alias/subject | No |
| Read one complete template from one Agent | No |
| Dump every full template (HTML/text/subject) from one Agent as JSON for local backup | No |
| Create a template in one explicit Agent | Yes |
| Partial update with Agent + stale-write protection | Yes |
| Permanent delete with Agent/name/timestamp checks | Yes |
Write tools require both:
ZEPTOMAIL_MCP_ALLOW_WRITES=truein the server environment.confirm=truein the individual tool call.
Every write also requires the exact agentKey and expectedAgentName from a fresh zeptomail_list_agents call. Update/delete additionally require current template safety values (expectedModifiedTime, expectedTemplateName), so a stale read can never overwrite a newer edit.
Configuration reference
Variable | Required | Default | Purpose |
| yes | — | Zoho OAuth app client ID |
| yes | — | Zoho OAuth app client secret |
| yes (stdio) | — | Long-lived token; the server mints 1-hour access tokens from it |
| no |
| Zoho data center ( |
| no |
| ZeptoMail API base URL |
| no |
| Set |
| no | all agents | Comma-separated |
| no |
|
|
All variables can be provided either as process environment variables (set by the host config) or via a --env-file=<path> argument to the server (see Configure your MCP host above). Process vars take precedence; the file only fills vars that are unset.
Hosted (remote) mode with OAuth 2.0 + PKCE
For a shared/public MCP endpoint, run with ZEPTOMAIL_MCP_TRANSPORT=http. The server becomes an OAuth authorization server that proxies to Zoho as the upstream authorization server:
MCP client ⇄ this MCP server (OAuth AS + resource server) ⇄ Zoho (upstream AS) ⇄ ZeptoMail APIZEPTOMAIL_MCP_TRANSPORT=http \
ZEPTOMAIL_MCP_SERVER_URL=https://mcp.example.com \
ZEPTOMAIL_MCP_PORT=3006 \
ZEPTOMAIL_MCP_TOKEN_STORE=/var/lib/zeptomail-mcp/tokens.json \
node dist/src/server.jsClients discover metadata at
/.well-known/oauth-protected-resourceand/.well-known/oauth-authorization-server, dynamically register, and consent in the browser.The server redirects to Zoho with the client's PKCE S256 challenge and
access_type=offline, exchanges the code with the server's Zoho client secret, and stores a per-client Zoho refresh token that never leaves the server.Each user's tools operate on their own ZeptoMail account.
Host config (opencode):
{
"mcp": {
"zeptomail": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": {}
}
}
}Requirements for hosted mode: HTTPS (the SDK rejects non-HTTPS issuer URLs except localhost), the Zoho callback URI registered in the API console (https://mcp.example.com/callback), and a persistent token store. Restarting the server invalidates issued tokens — clients re-consent once.
Development
npm install
npm run typecheck
npm test
npm run buildSecurity notes
Agent discovery is read-only; there are no tools for creating Agents, generating API keys, or accessing Send Mail Tokens.
The MCP never sends email.
ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYSconstrains which Agents the MCP may touch even when the OAuth account can see more.The refresh token is a long-lived credential: keep it server-side, treat it like a password, and revoke it in the Zoho console if it ever leaks.
Available Tools
8 toolszeptomail_create_templateCreate ZeptoMail templateA
Create a template in one explicit Agent. Requires agentKey plus expectedAgentName from a fresh zeptomail_list_agents call, server writes enabled, and confirm=true.
Inputs: subject (required), agentKey (required), templateName (required), expectedAgentName (required), +4 more.
zeptomail_delete_templateDelete ZeptoMail templateADestructiveIdempotent
Permanently delete a template from one explicit Agent. Requires expectedAgentName, expectedTemplateName, and expectedModifiedTime from fresh reads. Requires writes enabled and confirm=true.
Inputs: agentKey (required), templateKey (required), expectedAgentName (required), expectedModifiedTime (required), +2 more.
zeptomail_export_templatesExport all ZeptoMail templates from one AgentARead-onlyIdempotent
Fetch every full template (HTML body, text body, subject, alias, attachments metadata) from one explicit Agent and return them as a single JSON dump. Read-only. Use when the caller wants to back up an Agent templates to local files; the caller writes the files itself — this tool returns the data, it does not write to disk.
Inputs: agentKey (required).
zeptomail_find_templatesFind ZeptoMail templatesARead-onlyIdempotent
Search template name, alias and subject. Omit agentKey to search across every accessible Agent; provide agentKey to restrict the search to one Agent. Results always include the owning Agent.
Inputs: query (required), agentKey, maxResults.
zeptomail_get_templateGet ZeptoMail templateARead-onlyIdempotent
Fetch one complete template from one explicit Agent by exact template key. Always call this before updating or deleting.
Inputs: agentKey (required), templateKey (required).
zeptomail_list_agentsList ZeptoMail AgentsARead-onlyIdempotent
List accessible Agents in the ZeptoMail account. Returns each Agent name and exact mailagent_key (Agent alias). Always use the returned key for template tools; do not guess Agent identifiers.
Inputs: no named parameters.
zeptomail_list_templatesList ZeptoMail templatesARead-onlyIdempotent
List templates in one explicit ZeptoMail Agent. Use zeptomail_list_agents first and pass the exact returned mailagent_key.
Inputs: agentKey (required), limit, offset.
zeptomail_update_templateUpdate ZeptoMail templateADestructiveIdempotent
Partially update a template in one explicit Agent. Requires expectedAgentName and expectedModifiedTime from fresh reads so a stale or wrong-Agent edit is rejected. Requires writes enabled and confirm=true.
Inputs: agentKey (required), templateKey (required), expectedAgentName (required), expectedModifiedTime (required), +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource and action: agents vs templates, and list/search/get/export/create/update/delete are clearly separated. Even the similar list_templates and find_templates are disambiguated by one being an enumeration and the other being a search across name, alias, and subject.
All tool names use the consistent zeptomail_ prefix followed by verb_noun snake_case, such as zeptomail_list_agents and zeptomail_update_template. The naming pattern is uniform and predictable across the entire set.
Eight tools is well-scoped for a ZeptoMail template management server. Each tool covers a necessary operation without redundancy or bloat, and the count is within the ideal range for a focused domain server.
The tool surface provides full lifecycle coverage for templates: list, search, get, export, create, update, and delete. Agent enumeration supports the required context for template operations, so agents can accomplish end-to-end template management without dead ends.
Related MCP Connectors
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Governed email for agents: Gmail, M365 and IMAP; per-mailbox permissions, send allowlist, audit log
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides full access to Zoho Mail accounts, enabling email search, read, send, reply, thread management, folder/label operations, and more via 14 tools.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to read, send, search, reply to, and delete emails directly from a Zoho Mail account.8MIT
- FlicenseCqualityDmaintenanceEnables AI assistants to manage Zoho Mail accounts, including sending/receiving emails, folder and label management, organization administration, and productivity tools like tasks and notes.782-