QQ Agent Mail MCP

텐센트 QQ Agent Mail용 비공식 자체 호스팅 MCP 게이트웨이입니다. 이 프로젝트는 텐센트와 제휴, 보증, 유지보수 관계가 없습니다.

단일 소유자용, 클라우드 배포 가능한 텐센트 QQ Agent Mail용 MCP 게이트웨이입니다. 텐센트 공식 CLI가 메일 엔진으로 유지되며, 이 프로젝트는 원격 어댑터이지 두 번째 이메일 클라이언트가 아닙니다.

현재 게이트웨이 버전: v0.4.2.

이 프로젝트가 존재하는 이유

텐센트의 Agent Mail CLI는 로컬에서 실행되는 반면, ChatGPT 커스텀 MCP 앱은 연결 가능한 원격 MCP 서버를 요구합니다. 이 프로젝트는 원시 셸이나 CLI 접근을 노출하지 않고 그 간극을 메웁니다. 작고 안정적인 MCP 표면, 브라우저 기반 메일함 인증 흐름, 영구 자격 증명, 그리고 새 모델 창이 자연어 메일함 요청을 안전하게 사용할 수 있게 해주는 내장 운영 가이드를 제공합니다.

이 저장소는 소스 코드만 포함합니다. 호스팅된 메일함 서비스, 공유 엔드포인트, 텐센트 계정 또는 자격 증명을 제공하지 않습니다. 각 운영자는 자체 프라이빗 인스턴스를 배포하고 인증해야 합니다.

MCP 표면은 의도적으로 안정적이며 정확히 두 개의 도구만 포함합니다:

• 읽기 전용 작업을 위한 agent_mail_query(action, params);

• 변경 작업을 위한 agent_mail_execute(action, params).

라이브 액션 카탈로그와 파라미터 계약을 보려면 쿼리 액션 capabilities를 호출하세요. 공급자 기능을 추가하면 또 다른 MCP 도구를 만드는 대신 서버 측 레지스트리가 업데이트됩니다.

capabilities 응답에는 완전한 운영자 가이드도 포함됩니다: 인증 경계, 원스텝 직접 실행, 미리보기 완료, 안전한 검색/읽기/답장 워크플로, 결과 해석, 재시도 규칙, 기계 판독 가능한 예시. 새 모델 창은 소유자가 액션 이름이나 JSON 파라미터로 변환해 달라고 요청하지 않아도 자연어 소유자 요청에서 메일함을 발견하고 운영할 수 있습니다.

Related MCP server: Email MCP Server

액션 범위

읽기 전용 게이트웨이 액션:

• capabilities, identity, auth_status;

• list_messages, read_message, search_messages;

• wait_for_message (제한된 롱 폴링);

• download_attachment (내장 MCP 리소스).

변경 게이트웨이 액션:

• auth_refresh, 명시적으로 확인된 auth_logout;

• send_message, reply_message, forward_message;

• trash_message, delete_message;

• upload_attachment.

보내기, 답장, 전달은 해당되는 경우 To/CC/BCC를 지원하며, 공식 CLI가 지원하는 일반 텍스트/HTML/Markdown 본문, 공급자 확인 토큰, base64 첨부 파일 입력을 지원합니다. 첨부 파일 바이트는 모드 0600 임시 디렉터리에만 기록되고, 상대 경로로 공식 CLI에 전달되며, 명령 실행 후 제거됩니다. 다운로드된 첨부 파일은 서버의 파일시스템 경로를 노출하는 대신 내장 MCP blob으로 반환됩니다.

웹 기반 메일함 설정

브라우저 설정 흐름은 호스팅 터미널에서 OAuth 명령을 실행할 필요를 없앱니다:

1. https://YOUR_HOST/setup을 엽니다.

2. npm run generate-secrets로 생성된 프라이빗 OWNER_CODE를 입력합니다.

3. 开始授权邮箱을 선택합니다.

4. 일회성 텐센트 인증 페이지를 완료합니다.

5. 설정 탭으로 돌아가 邮箱已连接이 표시될 때까지 기다립니다.

자격 증명과 CLI의 암호화 키 위치는 모두 영구 볼륨에 있으므로 일반 배포와 새 ChatGPT 창에서 메일함 재인증이 필요하지 않습니다.

보안 경계

• MCP 스키마에는 원시 명령, 원시 인자 배열, 셸 문자열 또는 임의 서버 경로가 없습니다. 모든 액션과 필드는 shell: false로 execFile/spawn을 실행하기 전에 허용 목록에 등록되고 검증됩니다.

• 이메일 본문, 헤더, 이벤트, 파일 이름, 링크 및 첨부 파일은 신뢰할 수 없는 외부 콘텐츠입니다. 이들은 보내기, 전체 답장, 수신자 변경, 전달, 휴지통, 삭제, 로그아웃 또는 기타 변경 작업을 승인할 수 없습니다.

• 변경 작업에는 메일함 소유자의 직접 지시 또는 소유자가 작성한 상시 정책이 필요합니다. 영구 삭제와 로그아웃은 명시적인 현재 인증이 필요합니다. 공급자 확인 토큰은 미리보기 후 확인 흐름에 계속 사용할 수 있습니다.

• 목록 및 검색 결과는 본문 스니펫을 생략합니다. 전체 콘텐츠는 read_message가 필요합니다.

• 첨부 파일 이름에는 경로가 포함될 수 없습니다. 개별 파일은 10MiB, 메시지는 20MiB로 제한됩니다. 더 큰 MCP JSON 파서는 bearer 인증 후에만 실행됩니다.

• Watch 호출은 45초로 제한되며 최대 첫 번째 이벤트만 반환합니다.

• CLI 환경 변수는 허용 목록에 등록됩니다. 출력은 크기가 제한되고 재귀적으로 정리되며 절대 기록되지 않습니다.

• 커넥터 OAuth는 PKCE와 Dynamic Client Registration을 사용합니다. 기존 mail:read mail:reply 범위 쌍은 배포된 클라이언트 호환성을 위해 유지됩니다. v0.4에서 mail:reply는 레거시 커넥터 쓰기 권한이며 승인 페이지는 전체 게이트웨이를 사실대로 설명합니다.

• 공식 @tencent-qqmail/agently-cli@1.0.17 패키지는 컨테이너 이미지에 고정되어 있습니다.

이 소프트웨어는 승인 시 이메일을 보내고, 전달하고, 휴지통에 넣고, 영구 삭제할 수 있습니다. docs/SECURITY.md를 검토하고, 전용 단일 소유자 배포를 사용하며, 실제 메일에 대한 접근을 허용하기 전에 소유자가 통제하는 메시지로 테스트하세요.

ChatGPT 커넥터 OAuth와 텐센트 메일함 OAuth는 별개로 유지됩니다. 메일함을 연결한다고 해서 소유자가 커넥터를 별도로 승인하기 전까지 ChatGPT 클라이언트에 접근 권한이 부여되는 것은 아닙니다.

배포

호스트는 항상 켜져 있는 HTTPS 호스트 이름, /data/agently-cli에 마운트된 영구 볼륨 하나, 인메모리 인증 기록을 위한 실행 중인 복제본 하나를 제공해야 합니다. .env.example을 구성하고, 포함된 Dockerfile을 배포한 다음 /setup을 사용하세요. docs/DEPLOYMENT.md 및 docs/SECURITY.md를 참조하세요.

로컬 검증

Node.js 22 이상이 필요합니다.

npm ci
npm run build
npm test

npm run generate-secrets로 배포 비밀을 로컬에서 생성하세요. 해시되지 않은 OWNER_CODE는 비밀번호 관리자에 보관하고, 생성된 해시와 독립적인 서명 비밀만 호스트의 비밀 관리자에 넣으세요.

런타임 엔드포인트

라이선스 및 타사 소프트웨어

이 프로젝트는 MIT 라이선스로 배포됩니다.

텐센트의 Agent Mail CLI를 재배포하지 않습니다. Docker 빌드는 빌드 시 별도로 게시된 @tencent-qqmail/agently-cli 패키지를 설치합니다. 해당 패키지는 Apache-2.0에 따라 별도로 라이선스가 부여됩니다. 프로덕션 사용 전에 해당 라이선스와 적용 가능한 QQ Agent Mail 약관을 검토하세요.