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-mcp

This 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

1. Open the Zoho API Console.
2. Create a Server-based Application:
   • Client name: zeptomailmcp (no hyphens — Zoho rejects them)
   • Homepage URL: anything, e.g. https://github.com/P4rthPat3l/zeptomail-mcp
   • Authorized redirect URI: http://localhost:4567/callback
3. 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-login

Your 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.com

Then 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"] + the environment block
• Claude Desktop: "command": "node", "args": [".../dist/src/cli.js", "--env-file=..."] (or just [".../dist/src/cli.js"] with the env block)

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"

Self Client setup

A Self Client has no redirect URI, so zeptomail-mcp-login cannot catch its callback. Instead:

1. API Console → Self Client → Generate Code.
2. Scope: Zeptomail.MailAgents.READ,Zeptomail.MailTemplates.All → CREATE.
3. 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 | | ---------------------------- | ------------------------------------------------------------------------------------ | ------------ | | zeptomail_list_agents | List accessible Agents and exact Agent keys/aliases | No | | zeptomail_list_templates | List templates in one explicit Agent | No | | zeptomail_find_templates | Search one Agent or all Agents by name/alias/subject | No | | zeptomail_get_template | Read one complete template from one Agent | No | | zeptomail_export_templates | Dump every full template (HTML/text/subject) from one Agent as JSON for local backup | No | | zeptomail_create_template | Create a template in one explicit Agent | Yes | | zeptomail_update_template | Partial update with Agent + stale-write protection | Yes | | zeptomail_delete_template | Permanent delete with Agent/name/timestamp checks | Yes |

Write tools require both:

1. ZEPTOMAIL_MCP_ALLOW_WRITES=true in the server environment.
2. confirm=true in 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 | | ---------------------------------- | ----------- | -------------------------------- | --------------------------------------------------------------- | | ZOHO_CLIENT_ID | yes | — | Zoho OAuth app client ID | | ZOHO_CLIENT_SECRET | yes | — | Zoho OAuth app client secret | | ZOHO_REFRESH_TOKEN | yes (stdio) | — | Long-lived token; the server mints 1-hour access tokens from it | | ZOHO_ACCOUNTS_URL | no | https://accounts.zoho.com | Zoho data center (.eu, .in, .au, ...) | | ZEPTOMAIL_API_BASE_URL | no | https://api.zeptomail.com/v1.1 | ZeptoMail API base URL | | ZEPTOMAIL_MCP_ALLOW_WRITES | no | false | Set true to enable create/update/delete | | ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYS | no | all agents | Comma-separated mailagent_key allowlist | | ZEPTOMAIL_MCP_TRANSPORT | no | stdio | http enables the hosted OAuth mode (below) |

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 API

ZEPTOMAIL_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.js

• Clients discover metadata at /.well-known/oauth-protected-resource and /.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 build

Security 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_KEYS constrains 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.