ZeptoMail Templates MCP

MCP-сервер, который позволяет ИИ-агенту (opencode, Claude Desktop, Cursor и т. д.) просматривать и управлять шаблонами электронной почты во всех агентах ZeptoMail в вашем аккаунте Zoho.

Он намеренно не отправляет электронные письма, не создаёт/удаляет агентов, не раскрывает токены отправки почты и не управляет доменами. Он только читает список агентов и управляет шаблонами.

Быстрый старт (локально, ~5 минут)

1. Установите сервер

npm i -g zeptomail-mcp

Это даёт вам команду zeptomail-mcp в PATH. Пропустите этот шаг, если предпочитаете запускать из локального клона репозитория (node /path/to/zeptomail-mcp/dist/src/server.js).

2. Создайте приложение Zoho OAuth

1. Откройте консоль API Zoho.

2. Создайте серверное приложение:

   • Имя клиента: zeptomailmcp (без дефисов — Zoho их отклоняет)

   • URL домашней страницы: любой, например https://github.com/P4rthPat3l/zeptomail-mcp

   • Авторизованный URI перенаправления: http://localhost:4567/callback

3. Запишите Client ID и Client Secret.

Self Client также работает. У него нет поля redirect URI, поэтому вместо шага 2 используйте его вкладку Generate Code (см. Настройка Self Client ниже).

3. Получите refresh-токен

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

Ваш браузер откроет экран согласия Zoho для областей Zeptomail.MailAgents.READ + Zeptomail.MailTemplates.All. После одобрения скрипт выведет refresh-токен.

Если вы запускаете из локального клона вместо глобальной установки, эта же команда — 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"

• "найти шаблон с псевдонимом team_invite"

• "показать шаблон OTP в песочнице агента"

Related MCP server: Zoho Mail MCP Server

Настройка Self Client

У Self Client нет redirect URI, поэтому zeptomail-mcp-login не может перехватить его callback. Вместо этого:

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 в вызове отдельного инструмента.

Каждая запись также требует точных значений agentKey и expectedAgentName из нового вызова zeptomail_list_agents. Обновление/удаление дополнительно требует текущих значений безопасности шаблона (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, динамически регистрируются и дают согласие в браузере.

• Сервер перенаправляет на Zoho с PKCE S256 challenge клиента и access_type=offline, обменивает код на секрет клиента Zoho сервера и сохраняет индивидуальный refresh-токен Zoho для каждого клиента, который никогда не покидает сервер.

• Инструменты каждого пользователя работают с его собственным аккаунтом ZeptoMail.

Конфигурация хоста (opencode):

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

Требования для размещённого режима: HTTPS (SDK отклоняет не-HTTPS URL эмитента, кроме localhost), URI обратного вызова Zoho, зарегистрированный в консоли API (https://mcp.example.com/callback), и постоянное хранилище токенов. Перезапуск сервера делает выпущенные токены недействительными — клиенты повторно дают согласие один раз.

Разработка

npm install
npm run typecheck
npm test
npm run build

Замечания по безопасности

• Обнаружение агентов доступно только для чтения; нет инструментов для создания агентов, генерации API-ключей или доступа к токенам отправки почты.

• MCP никогда не отправляет электронные письма.

• ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYS ограничивает, к каким агентам MCP может обращаться, даже если учётная запись OAuth видит больше.

• Refresh-токен — это долгоживущее учётное данное: храните его на стороне сервера, относитесь к нему как к паролю и отзывайте его в консоли Zoho, если он когда-либо утечёт.