ZeptoMail Templates MCP

AIエージェント（opencode、Claude Desktop、Cursorなど）が、Zohoアカウント内のすべてのZeptoMailエージェントにわたってメールテンプレートを閲覧・管理できるようにするMCPサーバーです。

このサーバーは、メールの送信、エージェントの作成・削除、Send Mailトークンの公開、ドメインの管理を意図的に行いません。エージェント一覧の読み取りとテンプレートの管理のみを行います。

クイックスタート（ローカル、約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とクライアントシークレットを控えます。

セルフクライアントも利用可能です。リダイレクトURIフィールドがないため、手順2の代わりにそのコード生成タブを使用します（下記のセルフクライアントのセットアップを参照）。

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で直接実行します。グローバルのzeptomail-mcpコマンドと同じように--env-fileを解析するため、フラグはスクリプトの後に置きます：

• 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=..."]（またはenvブロック付きで[".../dist/src/cli.js"]のみ）

5. 使用する

エージェントにツールの呼び出しを依頼します：

• 「ZeptoMailエージェントを一覧表示して」

• 「エイリアスteam_inviteのテンプレートを探して」

• 「サンドボックスエージェントのOTPテンプレートを表示して」

Related MCP server: Zoho Mail MCP Server

セルフクライアントのセットアップ

セルフクライアントにはリダイレクトURIがないため、zeptomail-mcp-loginはそのコールバックを受け取れません。代わりに：

1. APIコンソール → セルフクライアント → コード生成。

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はlocalhost以外の非HTTPS発行者URLを拒否します）、APIコンソールに登録されたZohoコールバックURI（https://mcp.example.com/callback）、永続的なトークンストア。サーバーを再起動すると発行済みトークンが無効になります — クライアントは一度再同意します。

開発

npm install
npm run typecheck
npm test
npm run build

セキュリティに関する注意

• エージェントの検出は読み取り専用です。エージェントの作成、APIキーの生成、Send Mailトークンへのアクセスを行うツールはありません。

• MCPはメールを送信しません。

• ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYSは、OAuthアカウントがより多くを表示できる場合でも、MCPが操作できるエージェントを制限します。

• リフレッシュトークンは長期有効な認証情報です。サーバー側に保管し、パスワードと同様に扱い、漏洩した場合はZohoコンソールで失効させてください。