ZeptoMail Templates MCP

Ein MCP-Server, der es einem KI-Agenten (opencode, Claude Desktop, Cursor, ...) ermöglicht, E-Mail-Vorlagen über alle ZeptoMail-Agenten in Ihrem Zoho-Konto zu prüfen und zu verwalten.

Es sendet absichtlich keine E-Mails, erstellt/löscht keine Agenten, legt keine Send-Mail-Tokens offen und verwaltet keine Domains. Es liest nur die Agentenliste und verwaltet Vorlagen.

Schnellstart (lokal, ~5 Minuten)

1. Server installieren

npm i -g zeptomail-mcp

Dies gibt Ihnen einen zeptomail-mcp-Befehl in Ihrem PATH. Überspringen Sie dies, wenn Sie lieber aus einem lokalen Klon des Repos ausführen möchten (node /path/to/zeptomail-mcp/dist/src/server.js).

2. Zoho-OAuth-App erstellen

1. Öffnen Sie die Zoho API Console.

2. Erstellen Sie eine Server-basierte Anwendung:

   • Client-Name: zeptomailmcp (keine Bindestriche — Zoho lehnt sie ab)

   • Homepage-URL: beliebig, z. B. https://github.com/P4rthPat3l/zeptomail-mcp

   • Autorisierte Weiterleitungs-URI: http://localhost:4567/callback

3. Notieren Sie die Client-ID und das Client-Geheimnis.

Ein Self Client funktioniert ebenfalls. Er hat kein Feld für die Weiterleitungs-URI, verwenden Sie stattdessen dessen Registerkarte Code generieren (siehe Self-Client-Einrichtung unten).

3. Refresh-Token abrufen

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

Ihr Browser öffnet Zohos Zustimmungsbildschirm für die Bereiche Zeptomail.MailAgents.READ + Zeptomail.MailTemplates.All. Nachdem Sie zustimmen, gibt das Skript ein Refresh-Token aus.

Wenn Sie aus einem lokalen Klon statt einer globalen Installation ausführen, lautet derselbe Befehl npm run login.

4. MCP-Host konfigurieren

Sie können die Zoho-Anmeldedaten inline in der Host-Konfiguration übergeben oder sie aus einer .env-Datei laden, sodass die Konfigurationsdatei selbst geheimnisfrei bleibt. Beides funktioniert; wählen Sie eine Option.

Option A — aus einer .env-Datei laden (empfohlen)

Legen Sie die Geheimnisse in einer .env-Datei ab (gitignore sie — es handelt sich um Anmeldedaten):

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

Weisen Sie den Server dann mit --env-file darauf hin. Der Pfad wird relativ zum Arbeitsverzeichnis des Hosts aufgelöst; verwenden Sie bei Unsicherheit einen absoluten Pfad.

opencode — opencode.json (oder .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 der Host-Konfiguration

opencode — opencode.json (oder .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"
      }
    }
  }
}

Aus einem lokalen Klon statt einer globalen Installation ausführen

Führen Sie den gebauten Launcher direkt mit node aus. Er analysiert --env-file auf dieselbe Weise wie der globale Befehl zeptomail-mcp, daher steht das Flag nach dem Skript:

• 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"] + den environment-Block

• Claude Desktop: "command": "node", "args": [".../dist/src/cli.js", "--env-file=..."] (oder einfach [".../dist/src/cli.js"] mit dem env-Block)

5. Verwenden Sie es

Bitten Sie Ihren Agenten, die Tools aufzurufen:

• „Listen Sie meine ZeptoMail-Agenten auf“

• „finde die Vorlage mit dem Alias team_invite“

• „zeig mir die OTP-Vorlage im Sandbox-Agenten“

Related MCP server: Zoho Mail MCP Server

Self-Client-Einrichtung

Ein Self Client hat keine Weiterleitungs-URI, daher kann zeptomail-mcp-login seinen Callback nicht abfangen. Stattdessen:

1. API-Konsole → Self Client → Code generieren.

2. Bereich: Zeptomail.MailAgents.READ,Zeptomail.MailTemplates.All → ERSTELLEN.

3. Kopieren Sie den generierten Code und tauschen Sie ihn aus:

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

Die JSON-Antwort enthält refresh_token.

Werkzeuge

Schreibwerkzeuge erfordern beides:

1. ZEPTOMAIL_MCP_ALLOW_WRITES=true in der Serverumgebung.

2. confirm=true im einzelnen Tool-Aufruf.

Jeder Schreibvorgang erfordert außerdem den exakten agentKey und expectedAgentName aus einem frischen zeptomail_list_agents-Aufruf. Update/Löschen erfordern zusätzlich aktuelle Vorlagen-Sicherheitswerte (expectedModifiedTime, expectedTemplateName), sodass ein veralteter Lesevorgang niemals eine neuere Bearbeitung überschreiben kann.

Konfigurationsreferenz

Alle Variablen können entweder als Prozessumgebungsvariablen (vom Hostkonfiguration festgelegt) oder über ein --env-file=<path>-Argument an den Server bereitgestellt werden (siehe MCP-Host konfigurieren oben). Prozessvariablen haben Vorrang; die Datei füllt nur Variablen, die nicht gesetzt sind.

Gehosteter (Remote-)Modus mit OAuth 2.0 + PKCE

Für einen gemeinsamen/öffentlichen MCP-Endpunkt führen Sie mit ZEPTOMAIL_MCP_TRANSPORT=http aus. Der Server wird zu einem OAuth-Autorisierungsserver, der als Proxy zu Zoho als übergeordnetem Autorisierungsserver fungiert:

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 entdecken Metadaten unter /.well-known/oauth-protected-resource und /.well-known/oauth-authorization-server, registrieren sich dynamisch und stimmen im Browser zu.

• Der Server leitet mit der PKCE-S256-Herausforderung des Clients und access_type=offline an Zoho weiter, tauscht den Code mit dem Zoho-Client-Geheimnis des Servers aus und speichert ein pro Client Zoho-Refresh-Token, das den Server nie verlässt.

• Die Tools jedes Benutzers arbeiten mit seinem eigenen ZeptoMail-Konto.

Host-Konfiguration (opencode):

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

Anforderungen für den gehosteten Modus: HTTPS (das SDK lehnt Nicht-HTTPS-Issuer-URLs außer localhost ab), die in der API-Konsole registrierte Zoho-Callback-URI (https://mcp.example.com/callback) und ein persistenter Token-Speicher. Ein Neustart des Servers macht ausgestellte Tokens ungültig — Clients stimmen einmal erneut zu.

Entwicklung

npm install
npm run typecheck
npm test
npm run build

Sicherheitshinweise

• Die Agentenermittlung ist schreibgeschützt; es gibt keine Tools zum Erstellen von Agenten, Generieren von API-Schlüsseln oder Zugreifen auf Send-Mail-Tokens.

• Der MCP sendet niemals E-Mails.

• ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYS schränkt ein, welche Agenten der MCP berühren darf, auch wenn das OAuth-Konto mehr sehen kann.

• Das Refresh-Token ist eine langlebige Anmeldeinformation: Bewahren Sie es serverseitig auf, behandeln Sie es wie ein Passwort und widerrufen Sie es in der Zoho-Konsole, falls es jemals durchsickert.