MCP로 TrekMail에 AI 에이전트 연결하기

TrekMail MCP 서버를 사용하면 호환되는 AI 클라이언트가 자연어로 이메일 인프라를 관리할 수 있습니다. 이 카탈로그는 동일한 TrekMail API를 통해 도메인, 사서함, White Label 브랜딩과 팀, Drive, 이메일, 캘린더, 마이그레이션, 지원, 결제 및 관련 서비스를 다룹니다.

모든 대화에 전체 카탈로그가 로드되지는 않습니다. TrekMail은 활성 자격 증명을 기준으로 tools/list를 구성합니다. 자격 증명의 범위를 벗어난 도구는 제외되며, 선택한 도구 세트, 읽기 전용 모드, 전송 제한 또는 로컬 안전 설정에서 제외된 도구도 표시되지 않습니다. 따라서 범위가 엄격히 제한된 이메일 자격 증명에는 간결한 이메일 도구 목록만 나타납니다.

연결 방법 선택하기

경로 1-3은 OAuth 2.1을 사용합니다. 처음 연결하면 브라우저에서 TrekMail 동의 페이지가 열리고, 요청된 권한을 검토하면 클라이언트가 계정 범위로 제한된 토큰을 받습니다. 장기 tm_live_ 토큰을 클라이언트에 복사하지 않습니다. 언제든지 AI 에이전트 및 API → 토큰 → 연결된 앱에서 연결을 취소할 수 있습니다.

제공되는 기능

• 연결별 도구 세트는 등록 전에 현재 연결의 권한과 안전 설정에 맞게 필터링됩니다.
• OAuth 2.1 + 동적 클라이언트 등록: AI 클라이언트가 자체 등록하고 브라우저 동의 페이지를 안내한 뒤 범위가 제한된 토큰을 받습니다. 웹, 데스크톱 또는 CLI 경로에서는 장기 토큰을 복사하여 붙여넣을 필요가 없습니다.
• 이중 토큰 아키텍처: 운영 토큰(인프라)과 메시지 토큰(전체 웹메일 작업)을 분리합니다. OAuth로 연결하면 필요할 때마다 사서함별 메시지 토큰이 자동으로 발급됩니다.
• 자동 멱등성이 필요한 작업에 적용되므로 재시도해도 동일한 작업이 반복되지 않습니다.
• 두 단계 삭제: 사서함 삭제에는 명시적인 의도와 확인이 필요하며, 이후 복구할 수 있도록 최근 삭제 항목으로 이동합니다.
• 자체 호스팅 안전 제어: 자체 stdio MCP 서버를 실행하는 관리자는 삭제, 전송 및 마이그레이션 작업에 승인을 요구할 수 있습니다.
• 전체 감사 로깅: 모든 API 및 MCP 작업이 기록되며 90일 동안 보관됩니다.

시작하기 전에

• 모든 요금제에서 에이전트를 연결할 수 있습니다.
  • Nano: Email Verifier 도구를 제공합니다. Drive Storage를 추가하면 탐색, 업로드, 공유, 복원 및 영구 삭제 등 계정에 허용된 Drive 기능도 에이전트가 사용할 수 있습니다.
  • Starter: 전체 Drive, 전체 Email Verifier 및 나머지 영역(도메인, 사서함, 마이그레이션, 티켓 등)의 읽기 전용 액세스를 제공합니다. 마이그레이션 생성, 티켓 답변 또는 자동 회신 변경처럼 Starter가 API로 제공하지 않는 쓰기 작업에는 대시보드를 사용하세요.
  • Pro / Agency: 모든 도구 제품군에 대한 전체 읽기 및 쓰기 액세스를 제공합니다.
  • White Label 평가판 또는 애드온: 권한이 활성화된 동안 브랜딩, 클라이언트/팀 및 활동 도구를 추가합니다. 권한이 없으면 해당 스키마가 제외됩니다. 취소 유예 기간에는 소유자만 읽기 도구를 사용할 수 있습니다.
• 처음이신가요? AI 에이전트 및 API 페이지의 둘러보기 시작 버튼에서 에이전트 연결, 클라이언트별 단계, 수동 토큰, 연결된 앱 및 감사 로그를 안내합니다.
• **OAuth 경로 (1, 2, 3)**에서는 토큰을 직접 만들 필요가 없습니다. 클라이언트가 브라우저 승인 흐름을 통해 토큰을 생성합니다. **자체 호스팅 stdio 경로 (4)**에서는 먼저 대시보드에서 tm_live_ 토큰을 생성하세요.

1. 원격 MCP 클라이언트(권장)

AI 클라이언트가 원격 MCP 서버와 브라우저 승인을 지원할 때 이 경로를 사용하세요.

바로가기: AI 에이전트 및 API 페이지의 에이전트 연결 탭에서 사용하는 클라이언트를 선택하면 해당 클라이언트의 정확한 경로, 메뉴 위치 또는 구성 파일과 함께 주소가 이미 입력된 준비된 스니펫이 표시됩니다. 클라이언트가 목록에 있다면 아래의 일반 단계 대신 해당 안내를 따르세요.

1. 클라이언트에서 MCP, 통합 또는 커넥터 설정을 엽니다.
2. 원격 MCP 서버 추가 또는 사용자 지정 커넥터 추가를 선택합니다. 정확한 이름은 클라이언트마다 다릅니다.
3. 다음을 입력합니다.
   • 이름: TrekMail
   • 원격 MCP 서버 URL: https://trekmail.net/mcp
4. 연결을 확인합니다. 브라우저에서 TrekMail 승인 페이지가 열립니다.
5. 로그인하고 요청된 권한을 검토한 뒤 액세스를 승인합니다. 브라우저에서 연결을 확인하면 클라이언트로 돌아갑니다.

첫 승인 시 유효 시간이 제한된 토큰이 발급됩니다. 호환되는 클라이언트는 토큰을 자동으로 갱신합니다. 연결을 해제하려면 클라이언트의 연결 해제 작업을 사용하거나 TrekMail의 토큰 → 연결된 앱에서 앱을 취소하세요.

2. CLI 또는 데스크톱 클라이언트

stdio 명령을 허용하는 클라이언트에서는 아래의 클라이언트 중립적 브리지를 사용하세요.

npx -y mcp-remote https://trekmail.net/mcp

해당 명령을 클라이언트에서 MCP 서버로 구성합니다. 처음 연결하면 승인을 위해 브라우저가 열립니다.

일부 클라이언트는 원격 MCP 서버를 추가하는 자체 명령도 제공합니다. 이 방법도 동일하게 사용할 수 있습니다. 서버 URL로 https://trekmail.net/mcp를 사용하고 클라이언트의 안내를 따르세요.

클라이언트별 예시: Claude Code

claude mcp add trekmail https://trekmail.net/mcp -t http

클라이언트별 예시: Claude Desktop

구성 파일(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json)을 편집하고 다음을 추가합니다.

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp",
      "transport": "http"
    }
  }
}

Claude Desktop을 다시 시작합니다. 채팅에서 TrekMail을 처음 언급하면 OAuth 팝업이 열립니다.

클라이언트별 예시: Cursor

Cursor에는 원격 서버용 화면이 없습니다. ~/.cursor/mcp.json 또는 프로젝트 내부의 .cursor/mcp.json을 읽습니다.

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp"
    }
  }
}

클라이언트별 예시: Windsurf

Windsurf는 ~/.codeium/windsurf/mcp_config.json을 읽습니다. 키는 serverUrl이며 url이 아닙니다. 잘못된 url로 구성된 원격 서버는 무시됩니다.

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

파일을 저장하고 클라이언트를 다시 시작하여 변경 사항을 적용합니다. 처음 연결하면 액세스 승인을 위해 브라우저가 열립니다.

3. mcp-remote (CLI)

아직 원격 OAuth 서버를 직접 지원하지 않는 Anthropic 외 MCP 클라이언트나 테스트에 유용한 mcp-remote는 stdio에서 원격 HTTP로 연결하는 작은 Node 브리지입니다.

npx -y mcp-remote https://trekmail.net/mcp

처음 실행하면 OAuth를 위해 브라우저가 열립니다. 이후 토큰은 ~/.mcp-auth/에 캐시되어 자동으로 사용됩니다.

로컬 Node 진입점 대신 mcp-remote 명령을 가리키도록 설정하여 모든 stdio MCP 클라이언트에 연결할 수 있습니다.

4. 자체 호스팅 stdio (Claude Desktop / Docker / npm)

OAuth 대신 정적 tm_live_ 토큰을 사용하려면(예: 무인 서버, 비공개 TrekMail 인스턴스 또는 컨테이너 배포) stdio MCP 패키지를 복제하여 자체 호스트에서 실행하세요.

먼저 AI 에이전트 및 API → 토큰 페이지에서 API 토큰을 생성합니다. 이메일 읽기/전송에는 운영 토큰을 사용하여 API를 통해 메시지 토큰도 생성하세요(안내는 에이전트 연결 탭 참조).

MCP 서버 설치

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

Claude Desktop (stdio)

Claude Desktop MCP 구성 파일에 다음을 추가합니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

저장소를 복제한 위치를 가리키도록 args 경로를 업데이트합니다. 토큰을 자신의 값으로 바꾸세요. 인프라 도구만 필요하면 TREKMAIL_MESSAGE_TOKEN을 생략할 수 있고, 메시지 도구만 필요하면 TREKMAIL_API_TOKEN을 생략할 수 있습니다. 최소 하나의 토큰이 필요합니다.

Claude Code (stdio)

Claude Code MCP 설정(.claude/settings.json 또는 프로젝트 수준 구성)에 다음을 추가합니다.

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

Docker를 선호한다면 저장소에서 이미지를 빌드하고 실행합니다.

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

로컬 npm(개발)

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

Stdio 환경 변수

이 제어는 사용자가 실행하는 자체 호스팅 stdio MCP 프로세스에만 적용되며 TrekMail 제품 기능을 켜거나 끄지 않습니다.

에이전트용 Drive 도구

Drive 범위가 포함된 운영 토큰을 사용하면 MCP 서버는 공간, 사용량, 탐색, 업로드, 파일, 폴더, 휴지통, 대량 작업, 공개 공유 링크, 동기화 기기 비밀번호 관리 및 Drive Add-on 상태를 위한 도구를 제공합니다. 연결에는 해당 범위에서 허용하는 도구가 표시됩니다.

Drive 전용 에이전트에서는 TREKMAIL_API_TOKEN을 설정하고 워크플로에 필요한 범위만 부여하세요. 자체 호스팅 stdio를 실행할 때는 에이전트가 검토된 영구 삭제 또는 휴지통 비우기 작업을 수행하는 경우가 아니면 파괴적 작업을 비활성화하세요. Drive Add-on 구매, 크기 변경 및 취소는 MCP 도구가 아닙니다. 에이전트는 애드온 상태와 가격을 읽을 수 있지만 결제 변경은 대시보드에서 처리해야 합니다.

Drive MCP 도구 개요 및 TrekMail Drive에 AI 에이전트 연결하기를 참조하세요.

사용 가능한 도구

MCP 서버는 연결된 에이전트에 다음 도구를 제공합니다. 제공된 토큰에 따라 도구가 조건부로 등록됩니다.

에이전트가 실제로 볼 수 있는 도구는 다음 세 가지 요소로 결정되며, 모두 tools/list가 응답하기 전에 적용됩니다.

1. 토큰의 범위. 토큰에 해당 기능이 없는 도구는 등록되지 않습니다.
2. 로컬 stdio 안전 제어. 자체 호스팅 stdio 서버를 실행할 때 관리자는 쓰기, 전송 또는 마이그레이션 작업에 승인을 요구할 수 있습니다. 호스팅된 MCP는 대신 OAuth 중에 승인된 범위를 사용합니다.
3. **TREKMAIL_READ_ONLY=true**는 범위와 플래그에 관계없이 모든 쓰기 도구를 제거합니다.

따라서 토큰의 범위가 더 넓더라도 자체 호스팅 연결을 의도적으로 제한할 수 있습니다. 호스팅된 MCP는 OAuth 중에 승인된 권한으로 계속 제한됩니다.

도메인 도구(운영 토큰)

요금제 동작, 응답 상태, 안전한 제거 및 수신 전용 라우팅 규칙은 API 및 MCP를 통한 도메인 별칭을 참조하세요.

White Label 도구(운영 토큰)

white_label 도구 세트에는 20개 도구가 있으며 계정 권한, 현재 멤버십 및 자격 증명 범위가 허용할 때만 표시됩니다. 브랜딩은 도메인별로 구성되고 나머지 도구는 설정, 클라이언트, 팀 액세스 및 활동을 관리합니다. 쓰기에는 활성 White Label이 필요합니다. 취소 유예 기간에는 소유자만 읽기 도구를 유지합니다.

에이전트는 브랜드 설정을 처음부터 끝까지 실행할 수 있습니다. 브랜드를 설정하고 반환된 dns_records를 복사하여 apply_cloudflare_dns로 게시한 다음 확인하고 상태를 점검합니다. 액세스를 변경하는 호출은 토큰이 더 넓은 범위를 요청했더라도 호출자의 현재 멤버십과 도메인 경계로 제한됩니다. White Label 브랜딩 API 및 MCP 가이드와 API 및 MCP로 White Label 팀 관리하기를 참조하세요.

DNS 도구(운영 토큰)

사서함 도구(운영 토큰)

공유 사서함 도구(운영 토큰)

공유 사서함은 구성원이 Webmail에서 자신의 일반 사서함 계정을 통해 열고, 활성화된 경우 위임된 기본 IMAP/SMTP 액세스로 이용하는 팀 받은 편지함(support@, sales@)입니다. 직접 비밀번호 로그인은 없습니다. 액세스는 균일하며 모두 읽을 수 있고 can_send만 전환할 수 있습니다(답장 가능 또는 읽기 전용). 구성원 역할은 없습니다.

공유 사서함 수명 주기(운영 토큰)

세 가지 수명 주기 도구와 세 가지 구성원 쓰기 도구는 액세스를 변경합니다. 로컬 호스팅 stdio 관리자는 도구가 제공되기 전에 TREKMAIL_ALLOW_DESTRUCTIVE=true를 요구할 수 있습니다. list_shared_mailbox_members는 읽기 전용이며 항상 사용할 수 있습니다.

생성, 변환 또는 멤버십 변경 후 일반 구성원 사서함 id로 get_mail_client_setup을 호출하세요. shared_mailboxes.items[]를 읽고 native_access_ready=true를 기다린 다음 전송을 구성하기 전에 send_as_ready를 확인하세요. 응답은 정확한 받은 편지함/보낸 편지함/보관함/스팸 경로와 작업 플래그를 제공합니다. SMTP는 공유된 보낸 편지함 사본을 저장하지 않습니다. 권한 제거, 권한 업데이트 또는 변환에서 재시도 가능한 native_access_sync_failed가 발생하면 서비스가 의도적으로 이전 상태를 유지했다는 뜻입니다.

Sieve 도구(운영 토큰)

삭제 도구(운영 토큰)

마이그레이션 도구(운영 토큰)

티켓 도구(운영 토큰)

SMTP / 도메인 라우팅 도구(운영 토큰)

SMTP는 도메인별로 구성됩니다. 각 도메인은 관리형 플랫폼 전송 또는 저장된 SMTP 프로필(자체 제공업체, 여러 도메인에서 재사용 가능)을 가리키며, 계정 전체의 단일 기본값이 새 도메인의 초기 설정을 결정합니다.

위 쓰기 및 테스트 도구는 설정을 변경하거나 연결 테스트를 수행합니다. 로컬 호스팅 stdio 관리자는 도구가 제공되기 전에 TREKMAIL_ALLOW_DESTRUCTIVE=true를 요구할 수 있습니다. get_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_test_status 및 get_account_smtp_default는 읽기 전용이며 항상 사용할 수 있습니다.

레거시 SMTP 도구(지원 중단)

이 계정 수준 도구는 이전 버전과의 호환성을 위해 유지되지만 더 이상 도메인별 라우팅을 제어하지 않습니다. 대신 위 도메인 라우팅 도구를 사용하세요.

스팸 지표 도구(운영 토큰)

계정 도구(운영 토큰)

메시지 토큰 관리(운영 토큰)

메시지 도구(메시지 토큰)

메시지 토큰은 연결된 외부 계정을 포함한 전체 웹메일 영역의 62개 도구를 활성화합니다. 도구는 기능 영역별로 구성됩니다.

호스팅 OAuth와 로컬 stdio는 사서함을 서로 다르게 식별합니다. 호스팅 HTTP MCP에서 모든 메시지 도구 스키마에는 필수 mailbox_id가 포함되며, 서버는 이를 사용해 해당 사서함의 단기 토큰을 발급합니다. 로컬 stdio MCP에서 TREKMAIL_MESSAGE_TOKEN은 이미 하나의 사서함에 연결되어 있으므로 같은 도구가 mailbox_id를 받지 않습니다. 연결된 받은 편지함은 두 번째 선택 단계입니다. external_account_id를 전달하되, 호스팅 MCP에서는 mailbox_id와 함께 사용하고 stdio에서는 연결된 메시지 토큰과 함께 사용합니다.

62개의 메시지 도구 중 일곱 개는 연결된 계정을 관리하고 다섯 개는 보내는 사람 ID와 회신 정책을 관리합니다. 에이전트가 연결된 Gmail 받은 편지함을 읽지만 도메인 경로나 저장된 SMTP 프로필을 통해 승인된 비즈니스 주소로 보내는 Gmail 스타일 워크플로에는 두 제품군을 함께 사용하세요. API 및 MCP를 통한 보내는 사람 주소를 참조하세요.

핵심 메시지

사서함의 설정 → 프로필에서 기본 참조 또는 기본 숨은 참조를 설정한 경우 웹 앱에서 작성한 메일과 동일하게 send_message와 schedule_message의 전송 내용에 추가되며, 메시지에 이미 있는 주소는 두 번 추가되지 않습니다. 단일 메시지에서 제외하려면 apply_default_recipients: false를 전달하세요. API를 거치지 않는 데스크톱 또는 휴대폰 메일 클라이언트의 SMTP 전송에는 적용되지 않습니다. | report_spam | 메시지를 스팸으로 신고하고 정크로 이동한 뒤 필터 학습 | | report_ham | 정크 메시지를 스팸 아님으로 표시하고 받은 편지함으로 이동한 뒤 필터 학습 | | bulk_action | 한 번에 최대 50개 메시지에 작업(읽기, 별표, 삭제, 이동, 스팸) 적용 |

폴더

첨부 파일

임시 보관함

두 도구 모두 임시 보관 메시지의 uid와 uidvalidity를 반환합니다. 이 쌍을 함께 보관하세요. update_draft는 임시 보관함 폴더를 다시 만든 뒤 오래되어 재사용된 UID가 다른 메시지를 삭제하지 않도록 epoch를 요구합니다. list_messages로 찾은 임시 보관 메시지는 먼저 read_message로 열어 현재 uidvalidity를 받아야 합니다. 업데이트는 새 쌍을 반환하며 이전 UID는 작동하지 않습니다. UIDPLUS가 없는 서버에서는 새 임시 보관 메시지가 저장되었더라도 두 값이 모두 null일 수 있습니다. 업데이트하기 전에 임시 보관함을 새로 고치고 해당 메시지를 여세요.

두 도구 모두 선택적 idempotency_key도 허용합니다. 생략하면 모든 호출이 새 작업으로 처리되므로 같은 임시 보관 메시지를 두 번 저장하면 두 개가 생성됩니다. 이미 처리되었을 수 있는 호출을 재시도할 때 같은 키를 전달하면 중복 대신 첫 번째 결과를 받습니다.

예약 전송

연락처

연락처 그룹

캘린더

작성 도우미

이 도구는 회신 또는 전달을 위한 데이터를 준비하며 아무것도 전송하지 않습니다. 반환된 데이터를 send_message 또는 save_draft에 직접 전달하세요.

ID(보내는 사람 주소)

템플릿

차단된 발신자

Email Verifier 도구(운영 토큰)

Email Verifier 도구는 Nano를 포함한 모든 요금제에서 사용할 수 있습니다. 유일한 제한은 크레딧 잔액입니다.

Cloudflare 도구(운영 토큰)

Cloudflare 도구는 Pro 및 Agency 요금제에서 사용할 수 있습니다.

자체 호스팅 stdio 안전 제어

stdio MCP 서버를 직접 실행할 때 TREKMAIL_ALLOW_DESTRUCTIVE는 해당 로컬 프로세스가 삭제 및 기타 쓰기 작업을 허용할지 제어합니다. 에이전트가 사서함 삭제를 안전하게 처리한다고 신뢰할 때만 true로 설정하세요. 이 설정은 호스팅된 TrekMail의 기능 가용성을 변경하지 않습니다.

파괴적 작업이 활성화되어도 삭제에는 항상 두 단계가 필요하며 에이전트가 confirm: true를 명시적으로 설정해야 합니다. 자세한 내용은 안전 장치 및 삭제 의도를 참조하세요.

전송 안전 게이트

send_message 및 schedule_message 도구에는 모두 통과해야 하는 두 개의 독립적인 안전 게이트가 있습니다.

1. 환경 게이트: MCP 서버를 시작할 때 TREKMAIL_ALLOW_SENDING=true를 설정해야 합니다.
2. 호출별 게이트: 에이전트가 모든 호출에 confirm_send=true를 매개변수로 전달해야 합니다.

이중 게이트 설계는 자체 호스팅 프로세스에서 실수로 이메일을 보내는 것을 방지합니다. 에이전트가 메시지만 읽어야 한다면 TREKMAIL_ALLOW_SENDING=false로 설정하세요. list_scheduled는 이 제어 없이 작동하며, 이 제어는 예약 메시지 생성 또는 전송에만 적용됩니다.

마이그레이션 안전 게이트

마이그레이션 쓰기 도구(start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection, preview_bulk_migration, start_bulk_migration, retry_bulk_migration)에는 두 개의 독립적인 안전 게이트가 있습니다.

1. 환경 게이트: MCP 서버를 시작할 때 TREKMAIL_ALLOW_MIGRATION=true를 설정해야 합니다.
2. 호출별 게이트: 각 도구에는 자체 확인 매개변수(confirm_start=true, confirm_retry=true 또는 confirm_delete=true)가 필요합니다.

cancel_migration, cancel_bulk_migration 및 resume_bulk_migration은 안전 또는 재개 작업이므로 자체 호스팅 환경 제어와 관계없이 항상 사용할 수 있습니다. 여전히 호출별 확인 매개변수가 필요합니다.

읽기 전용 마이그레이션 도구(list_migrations, get_migration, list_bulk_migrations, get_bulk_migration)는 게이트 없이 작동합니다.

빠른 해결 방법

• 에이전트가 연결할 수 없음: build/index.js 경로가 올바른지, 복제 후 npm run build를 실행했는지 확인하세요.
• "Missing bearer token" 오류: TREKMAIL_API_TOKEN 또는 TREKMAIL_MESSAGE_TOKEN 중 하나 이상이 설정되었는지 확인하세요.
• 읽기 전용 도구는 작동하지만 쓰기가 실패함: 토큰이 Starter 요금제에 속합니다. Drive 쓰기는 Starter에서 작동합니다(전체 Drive 영역). 기타 쓰기, 사서함 프로비저닝, 마이그레이션 시작 또는 티켓 답변에는 Pro로 업그레이드하거나 대시보드를 사용하세요.
• 자체 호스팅 stdio에서 삭제 도구 오류: 해당 MCP 프로세스 환경에서 TREKMAIL_ALLOW_DESTRUCTIVE=true를 설정하세요. 메시지, 폴더, 연락처, 캘린더, ID, 템플릿, 차단된 발신자 및 예약 메시지를 포함한 삭제와 기타 쓰기 작업에 적용됩니다.
• 자체 호스팅 stdio 전송 도구가 "Sending is disabled"를 반환함: 해당 MCP 프로세스 환경에서 TREKMAIL_ALLOW_SENDING=true를 설정하세요.
• 전송 도구가 "Send not confirmed"를 반환함: 에이전트는 confirm_send=true를 전달해야 하며, 각 send_message 또는 schedule_message 호출에서 그렇게 해야 합니다.
• 메시지 도구가 표시되지 않음: TREKMAIL_MESSAGE_TOKEN이 유효한 tm_msg_ 토큰으로 설정되었는지 확인하세요.
• 자체 호스팅 stdio 마이그레이션 쓰기 도구 오류: 해당 MCP 프로세스 환경에서 TREKMAIL_ALLOW_MIGRATION=true를 설정하세요.
• 마이그레이션 시작 시 503: 서버가 마이그레이션 용량에 도달했습니다. 몇 분 후 다시 시도하세요.
• 첨부 파일 다운로드 실패: 첨부 파일은 base64로 반환됩니다. 대용량 첨부 파일(최대 25 MB)은 몇 초 정도 걸릴 수 있습니다. download_all_attachments는 모든 첨부 파일이 포함된 base64 인코딩 ZIP을 반환합니다.
• 업데이트 후 임시 보관 메시지가 사라짐: update_draft는 이전 메시지를 삭제하고 대체 메시지를 추가하므로 새 UID ID가 부여됩니다. 이후 작업에는 응답의 uid와 uidvalidity를 모두 사용하세요. 전달했던 쌍은 더 이상 대체 메시지를 식별하지 않습니다.
• 모든 메시지의 사본이 지정하지 않은 곳에 도착함: 사서함의 설정 → 프로필에 기본 참조 또는 기본 숨은 참조가 있습니다. API를 포함해 이 사서함이 보내는 항목에 적용됩니다. 해당 설정을 지우거나 한 메시지에서 제외하려면 apply_default_recipients: false를 전달하세요.
• 캘린더 일정을 찾을 수 없음: 일정은 특정 사서함으로 범위가 제한됩니다. 메시지 토큰이 올바른 사서함에 발급되었는지 확인하세요.