ZeptoMail Templates MCP

一个 MCP 服务器，让 AI 代理（opencode、Claude Desktop、Cursor 等）能够检查并管理你 Zoho 账户中所有 ZeptoMail Agent 的邮件模板。

它特意不发送邮件、不创建/删除 Agent、不暴露 Send Mail Token，也不管理域名。它只读取 Agent 列表并管理模板。

快速开始（本地，约 5 分钟）

1. 安装服务器

npm i -g zeptomail-mcp

这会在你的 PATH 上提供 zeptomail-mcp 命令。如果你更愿意从仓库的本地克隆运行，可以跳过这一步（node /path/to/zeptomail-mcp/dist/src/server.js）。

2. 创建 Zoho OAuth 应用

1. 打开 Zoho API 控制台。

2. 创建一个基于服务器的应用：

   • 客户端名称：zeptomailmcp（不要用连字符——Zoho 会拒绝）

   • 主页 URL：任意，例如 https://github.com/P4rthPat3l/zeptomail-mcp

   • 授权重定向 URI：http://localhost:4567/callback

3. 记下客户端 ID 和客户端密钥。

Self Client 也可以。它没有重定向 URI 字段，因此不用第 2 步，而是使用它的 Generate Code 标签页（见下文 Self Client 设置）。

3. 获取刷新令牌

ZOHO_CLIENT_ID=<your-client-id> ZOHO_CLIENT_SECRET=<your-secret> zeptomail-mcp-login

你的浏览器会打开 Zoho 的同意屏幕，请求作用域 Zeptomail.MailAgents.READ + Zeptomail.MailTemplates.All。批准后，脚本会打印一个刷新令牌。

如果你是从本地克隆而不是全局安装运行，同样的命令是 npm run login。

4. 配置你的 MCP 主机

你可以将 Zoho 凭据内联传入主机配置，或者从 .env 文件加载它们，这样配置文件本身就不含机密。两种方式都可行；任选其一。

选项 A — 从 .env 文件加载（推荐）

将机密放入 .env 文件（将其加入 gitignore——它是凭据）：

# .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

然后用 --env-file 将服务器指向它。路径相对于主机的当前工作目录解析；如果不确定，请使用绝对路径。

opencode — opencode.json（或 .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"]
    }
  }
}

选项 B — 在主机配置中内联

opencode — opencode.json（或 .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"
      }
    }
  }
}

从本地克隆而不是全局安装运行

直接用 node 运行构建好的启动器。它解析 --env-file 的方式与全局 zeptomail-mcp 命令相同，因此该标志放在脚本之后：

• opencode（选项 A env-file）：["node", "/absolute/path/to/zeptomail-mcp/dist/src/cli.js", "--env-file=/absolute/path/to/.env"]

• opencode（选项 B 内联）：["node", "/absolute/path/to/zeptomail-mcp/dist/src/cli.js"] + environment 块

• Claude Desktop："command": "node"，"args": [".../dist/src/cli.js", "--env-file=..."]（或仅 [".../dist/src/cli.js"] 加上 env 块）

5. 使用它

让你的代理调用这些工具：

• “列出我的 ZeptoMail agents”

• “找到别名为 team_invite 的模板”

• “显示 sandbox agent 中的 OTP 模板”

Related MCP server: Zoho Mail MCP Server

Self Client 设置

Self Client 没有重定向 URI，因此 zeptomail-mcp-login 无法捕获其回调。请改为：

1. API 控制台 → Self Client → Generate Code。

2. 作用域：Zeptomail.MailAgents.READ,Zeptomail.MailTemplates.All → CREATE。

3. 复制生成的代码并交换：

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/"

JSON 响应中包含 refresh_token。

工具

写入工具需要两者：

1. 服务器环境中设置 ZEPTOMAIL_MCP_ALLOW_WRITES=true。

2. 单个工具调用中设置 confirm=true。

每次写入还要求来自一次新的 zeptomail_list_agents 调用的确切 agentKey 和 expectedAgentName。更新/删除还要求当前的模板安全值（expectedModifiedTime、expectedTemplateName），因此过期的读取永远不会覆盖较新的编辑。

配置参考

所有变量都可以作为进程环境变量（由主机配置设置）提供，或通过 --env-file=<path> 参数提供给服务器（见上文 配置你的 MCP 主机）。进程变量优先；文件只填充未设置的变量。

托管（远程）模式，使用 OAuth 2.0 + PKCE

对于共享/公共 MCP 端点，使用 ZEPTOMAIL_MCP_TRANSPORT=http 运行。服务器成为 OAuth 授权服务器，代理到 Zoho 作为上游授权服务器：

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

• 客户端在 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server 发现元数据，动态注册，并在浏览器中同意。

• 服务器使用客户端的 PKCE S256 挑战和 access_type=offline 重定向到 Zoho，使用服务器的 Zoho 客户端密钥交换代码，并存储一个每客户端 Zoho 刷新令牌，该令牌永远不会离开服务器。

• 每个用户的工具操作他们自己的 ZeptoMail 账户。

主机配置（opencode）：

{
  "mcp": {
    "zeptomail": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {}
    }
  }
}

托管模式的要求：HTTPS（SDK 拒绝非 HTTPS 的 issuer URL，localhost 除外）、在 API 控制台中注册的 Zoho 回调 URI（https://mcp.example.com/callback），以及持久化令牌存储。重启服务器会使已颁发的令牌失效——客户端会重新同意一次。

开发

npm install
npm run typecheck
npm test
npm run build

安全说明

• Agent 发现是只读的；没有用于创建 Agent、生成 API 密钥或访问 Send Mail Token 的工具。

• MCP 从不发送邮件。

• ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYS 限制了 MCP 可以接触的 Agent，即使 OAuth 账户可以看到更多。

• 刷新令牌是长期凭据：将其保存在服务器端，像密码一样对待，如果泄露，请在 Zoho 控制台中撤销它。