ZeptoMail Templates MCP

AI 에이전트(opencode, Claude Desktop, Cursor 등)가 Zoho 계정의 모든 ZeptoMail Agent에서 이메일 템플릿을 검사하고 관리할 수 있게 해주는 MCP 서버입니다.

이 서버는 의도적으로 이메일을 보내지 않으며, 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 Console을 엽니다.

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로 직접 실행합니다. 전역 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

Self Client 설정

Self Client에는 리디렉션 URI가 없으므로 zeptomail-mcp-login이 콜백을 받을 수 없습니다. 대신:

1. API Console → 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로 실행합니다. 서버는 업스트림 인증 서버인 Zoho에 프록시하는 OAuth 인증 서버가 됩니다:

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

보안 참고 사항

• Agent 검색은 읽기 전용입니다. Agent 생성, API 키 생성, Send Mail Token 액세스 도구는 없습니다.

• MCP는 이메일을 절대 보내지 않습니다.

• ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYS는 OAuth 계정이 더 많이 볼 수 있어도 MCP가 접근할 수 있는 Agent를 제한합니다.

• 리프레시 토큰은 장기 자격 증명입니다. 서버 측에 보관하고, 비밀번호처럼 취급하며, 유출되면 Zoho 콘솔에서 폐기하세요.