zoho-multi-mcp

AI 어시스턴트(예: Claude)를 Zoho Mail 계정에 연결하는 MCP (Model Context Protocol) 서버입니다. AI 워크플로에서 직접 이메일을 읽고, 보내고, 검색하고, 답장하고, 삭제할 수 있습니다 — 그리고 사서함당 하나의 프로세스 대신 하나의 가벼운 프로세스에서 원하는 만큼의 Zoho 사서함을 실행할 수 있습니다.

이 프로젝트는 멀티 계정 지원이 추가된 FujiwaraChoki/zoho-mail-mcp의 포크입니다(MIT 라이선스, LICENSE 참조). 원래 단일 계정 서버에 대한 모든 공로는 업스트림 작성자에게 있습니다.

이 포크가 존재하는 이유

MCP를 통해 여러 Zoho 사서함을 실행한다면(팀, 프로젝트별 발신자 모음 등), 자연스러운 구성은 사서함당 하나의 서버 프로세스입니다. 그렇게도 동작하지만, 각 프로세스는 사서함이 아무리 작거나 유휴 상태여도 동일한 고정 Bun/V8 런타임 메모리 오버헤드(약 75-85MB RSS)를 부담합니다. 사서함 3개는 이 기준치의 3배를 아무 이득 없이 소비합니다. 실제 계정별 상태(OAuth 토큰, 폴더 캐시)는 아주 작기 때문입니다.

이 포크는 옵트인 방식의 멀티 계정 모드를 추가합니다. 하나의 프로세스가 여러 Zoho 계정을 제공할 수 있습니다. 호출자가 호출마다 계정을 지정하는 단일 엔드포인트로, 또는 기존 구성에 더 안전한 옵션으로 각각 고정 포트에서 수신 대기하는 여러 리스너로 동작하며, 각 리스너는 일반 단일 계정 서버와 똑같이 동작합니다. 프로덕션에서 측정한 결과: 3개의 분리된 단일 계정 프로세스가 합산 약 ~230MB RSS를 사용하던 것을, 동일한 3개 사서함을 제공하는 하나의 프로세스로 통합하여 약 ~90MB RSS로 줄였습니다. "멀티 계정 모드" 섹션 아래의 모든 내용은 업스트림에서 변경되지 않았으며, 사서함이 하나만 필요하다면 지금까지와 똑같이 작동합니다.

Related MCP server: Mailing Manager MCP

도구

설정

1. Zoho API 클라이언트 만들기

1. Zoho API Console로 이동합니다(US 데이터센터는 .com 사용)

2. Add Client > Self Client를 클릭합니다.

3. Client ID 및 Client Secret을 기록해 둡니다.

2. Refresh Token 생성

대화형 설정 도우미를 실행합니다:

bun run setup.ts

또는 수동으로:

1. Self Client에서 다음 범위로 승인 코드를 생성합니다:

   ZohoMail.accounts.READ,ZohoMail.folders.READ,ZohoMail.messages.READ,ZohoMail.messages.CREATE,ZohoMail.messages.DELETE

2. 기간을 10분으로 설정하고 설명을 추가한 다음 Create를 클릭합니다.

3. 생성된 코드를 복사하고 설정 스크립트를 사용하여 교환합니다.

3. 자격 증명 확인

ZOHO_CLIENT_ID=your_id ZOHO_CLIENT_SECRET=your_secret ZOHO_REFRESH_TOKEN=your_token bun run setup.ts --verify

4. MCP 클라이언트 구성

단일 계정 — Claude Code (~/.claude.json)

{
  "mcpServers": {
    "zoho-mail": {
      "command": "bun",
      "args": ["run", "/path/to/zoho-multi-mcp/src/index.ts"],
      "env": {
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_DATACENTER": "eu"
      }
    }
  }
}

Claude Desktop의 claude_desktop_config.json도 동일한 형식입니다.

멀티 계정 모드

이 서버를 통해 실행하려는 각 Zoho 계정에 대해 위 단계를 계정마다 한 번씩 반복한 다음, 두 가지 모드 중 하나를 선택합니다.

모드 A — 단일 엔드포인트, 호출자가 계정 선택

ZOHO_ACCOUNTS_JSON을 계정의 JSON 배열로 설정하고 평소처럼 ZOHO_HTTP_PORT로 서버를 시작합니다(또는 stdio). 모든 도구에는 필수 account 필드(지정한 id들의 문자열 enum)가 추가되며, 모든 호출은 어느 계정을 위한 것인지 명시해야 합니다.

export ZOHO_ACCOUNTS_JSON='[
  {"id": "work", "clientId": "...", "clientSecret": "...", "refreshToken": "..."},
  {"id": "personal", "clientId": "...", "clientSecret": "...", "refreshToken": "..."}
]'
export ZOHO_HTTP_PORT=8010
bun run src/index.ts

MCP 클라이언트가 모든 호출에 명시적인 account 인수를 사용해도 괜찮고, 구성할 단일 URL을 원할 때 적합합니다.

모드 B — 단일 프로세스, 여러 고정 계정 리스너

ZOHO_ACCOUNTS_JSON을 위와 같이 설정하고, ZOHO_MULTI_PORT_JSON을 설정하여 각 계정을 자체 포트에 바인딩합니다. 모든 리스너는 진정한 단일 계정 서버처럼 동작합니다. 어떤 도구에도 account 필드가 없으며, 해당 포트의 일반 단일 계정 구성과 바이트 단위로 동일합니다.

export ZOHO_ACCOUNTS_JSON='[
  {"id": "work", "clientId": "...", "clientSecret": "...", "refreshToken": "..."},
  {"id": "personal", "clientId": "...", "clientSecret": "...", "refreshToken": "..."}
]'
export ZOHO_MULTI_PORT_JSON='[
  {"id": "work", "port": 8010, "name": "zoho-mail-work"},
  {"id": "personal", "port": 8011, "name": "zoho-mail-personal"}
]'
bun run src/index.ts

이 모드는 기존 다중 프로세스 구성을 마이그레이션할 때 사용합니다. MCP 클라이언트 구성을 이미 사용 중인 동일한 포트를 가리키게 하고, 이전에 실행하던 여러 프로세스 대신 이 프로세스 하나를 시작하면 다른 것은 변경할 필요가 없습니다. name은 선택 사항이며 로그 줄 레이블에만 영향을 줍니다.

두 모드 모두 필수가 아닙니다. ZOHO_ACCOUNTS_JSON과 ZOHO_MULTI_PORT_JSON을 모두 생략하면 서버는 원래 업스트림 단일 계정 프로젝트와 똑같이 동작하며, ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET/ZOHO_REFRESH_TOKEN을 직접 읽습니다.

환경 변수

기능

• 자동 갱신 OAuth2 - 토큰이 자동으로 갱신되며 수동 개입이 필요 없고, 멀티 계정 모드에서는 계정별로 캐시됩니다.

• 속도 제한 - Zoho API 한도 내에서 유지하도록 내장된 슬라이딩 윈도우 속도 제한기(30 req/min)

• 401 시 재시도 - 인증 실패 시 토큰을 자동으로 갱신하고 재시도합니다.

• HTML을 일반 텍스트로 변환 - 이메일 내용이 AI가 소비하기 좋은 깨끗한 일반 텍스트로 변환됩니다.

• 멀티 계정, 낮은 메모리 - 위의 "이 포크가 존재하는 이유" 참조

요구 사항

• Bun 런타임

• API 액세스 권한이 있는 Zoho Mail 계정 하나 이상

라이선스

MIT (c) 2026 Sami Hindi — LICENSE 참조. 이 포크의 멀티 계정/멀티 포트 추가 기능은 동일한 라이선스로 배포됩니다.