QQ Agent Mail MCP

Una pasarela MCP no oficial y autoalojada para Tencent QQ Agent Mail. Este proyecto no está afiliado a Tencent, no cuenta con su respaldo ni está mantenido por Tencent.

Una pasarela MCP de un único propietario y desplegable en la nube para Tencent QQ Agent Mail. La CLI oficial de Tencent sigue siendo el motor del buzón; este proyecto es un adaptador remoto, no un segundo cliente de correo.

Versión actual de la pasarela: v0.5.0.

Por qué existe este proyecto

La CLI de Agent Mail de Tencent se ejecuta localmente, mientras que los clientes MCP remotos requieren un servidor alcanzable. Este proyecto cubre esa brecha sin exponer acceso directo a la shell ni a la CLI. Ofrece una superficie MCP pequeña y estable, autorización del buzón basada en navegador, credenciales persistentes, OAuth para clientes compatibles, tokens portadores con nombre para clientes con soporte de cabeceras personalizadas y una guía operativa integrada que permite que una nueva ventana de modelo utilice solicitudes de buzón en lenguaje natural de forma segura.

Este repositorio contiene solo el código fuente. No proporciona un servicio de buzón alojado, un endpoint compartido, una cuenta de Tencent ni credenciales. Cada operador debe desplegar y autorizar su propia instancia privada.

La superficie MCP es deliberadamente estable y contiene exactamente dos herramientas:

• agent_mail_query(action, params) para operaciones de solo lectura;

• agent_mail_execute(action, params) para mutaciones.

Invocar la acción agent_mail_query con el parámetro action de consulta capabilities para obtener el catálogo de acciones vigente y el contrato de parámetros. Añadir una capacidad de proveedor actualiza el registro del lado del servidor en lugar de crear una nueva herramienta MCP.

La respuesta de capabilities también contiene la guía completa del operador: límites de autorización, ejecución directa en un solo paso, confirmación de vista previa, flujo de búsqueda/lectura/respuesta segura, interpretación de resultados, reglas de reintentos y ejemplos legibles por máquina. Una ventana de modelo nueva puede descubrir y manejar el buzón a partir de una solicitud en lenguaje natural del propietario, sin que este tenga que traducirla a nombres de acciones ni a parámetros JSON.

Related MCP server: anymail-mcp

Compatibilidad de clientes

El transporte preferido es MCP Streamable HTTP en /mcp. También está disponible un endpoint de compatibilidad SSE heredado en /sse, con los mensajes de los clientes enviados a /messages.

• OAuth 2.1 con PKCE y Dynamic Client Registration sigue estando disponible para ChatGPT.

• Los clientes de escritorio o autoalojados que pueden establecer cabeceras personalizadas pueden usar un token portador con nombre generado de forma independiente como Authorization: Bearer YOUR_TOKEN.

• Cada cliente debe tener su propio token. Eliminar esa entrada de nombre de señales MCP_API_TOKENS y redesplegar revoca únicamente a ese cliente.

• Un proveedor de modelos como DeepSeek no se conecta directamente a este servidor; el host MCP detecta las dos herramientas y proporciona sus esquemas al modelo.

Genere una credencial de cliente no OAuth cada vez:

npm run generate-client-token -- polaris

Coloque la entrada client-id:token emitida en el secreto MCP_CLIENT_TOKENS de su despliegue. En el cliente, elija Streamable HTTP, use https://YOUR_HOST/mcp y añada una cabecera Authorization cuyo valor sea Bearer YOUR_TOKEN. Nunca comparta una URL de despliegue junto con su token, y nunca reutilice el secreto de firma de OAuth, el código de propietario ni las credenciales de Tencent como token de cliente.

Cobertura de acciones

Acciones de solo lectura de la pasarela:

• capabilities, identity, auth_status;

• list_messages, read_message, search_messages;

• wait_for_message (consulta larga acotada);

• download_attachment (recurso MCP incrustado).

Acciones de mutación de la pasarela:

• auth_refresh, auth_logout conconfirmación explícita;

• send_message, reply_message, forward_message;

• trash_message, delete_message;

• upload_attachment.

El envío, la respuesta y el reenvío admiten Para/Copiary con copia "blindada" según corresponda, cuerpos en texto sin formato/HTML/Markdown según lo admita la CLI oficial, tokens de confirmación del proveedor y datos adjuntos de entrada en base64. Los bytes de los adjuntos se escriben solo en un directorio temporal con modo 0600, se pasan a la CLI oficial mediante una ruta relativa y se eliminan tras el comando. Un adjunto descargado se devuelve como un blob MCP incrustado, sin exponer la ruta de archivos del servidor.

Configuración del buzón desde el navegador

El flujo de configuración en el navegador evita tener que ejecutar comandos OAuth en un terminal de servidor:

1. Abre https://YOUR_HOST/setup.

2. Introduce el OWNER_CODE privado creado por npm run generate-secrets.

3. Selecciona 开始授权邮箱.

4. Completa la página de autorización única de Tencent.

5. Vuelve a la pestaña de configuración y espera a ver 邮箱已连接.

Las credenciales y las ubicaciones de las claves de cifrado de la CLI viven en el volumen persistente, por lo que los despliegues normales y las nuevas ventanas de ChatGPT no requieren una autorización del buzón de nuevo.

Límite de seguridad

Para cada operador, el límite de seguridad es el siguiente:

• No hay mensajes crudos en el esquema MCP, ni listas o argumentos de shell, ni rutas arbitrarias del servidor. Cada acción y campo está en la lista de permitidos y se valida.

• El contenido del correo (cuerpos, cabeceras, eventos, nombres de archivo, enlaces y adjuntos) es externo y no es de confianza. No puede autorizar ninguna mutación.

• Las mutaciones se autorizan solo con una instrucción directa.

• Para las acciones de solo lectura, las llamadas list_messages and search_messages son de larga duración y requieren "permisos acotados" para 45 segundos a lo sumo.

• El cuerpo y archivos se pasan en entradas ya codificadas en base64.

• Las acciones auth_refresh y auth_logout requieren confirmación explícita.

• Cuando se usa OAuth 2.1 con PKCE, la autorización del conector usa un alcance de correo de solo lectura y respuesta.

• Sin blobs de adjuntos crudos en el lado MCP.

This software can send, forward, trash, and permanently delete email when authorized. Revisa docs/SECURITY.md, así como un despliegue de un solo propietario dedicado, y prueba con mensajes controlados por el propietario antes de dar acceso al correo real.

El OAuth del conector de ChatGPT y el OAuth del buzón de Tencent son independientes. Conectar el buzón no concede al clientel de ChatGPT acceso hasta que el propietario lo aprueba por separado.

Desplegar

El host proporcionar un nombre de host HTTPS siempre disponible, un volumen persistente montado en /data/agently-cli y una única réplica en ejecución para la autorización en memoria y los registros de sesiones SSE heredados. Configura .env.example, despliega el Dockerfile incluido y luego usa /setup. Consulta docs/DEPLOYMENT.md y docs/SECURITY.md.

Verificación local

Requiere Node.js 22 o más reciente.

npm ci
npm run build
npm test

Genera localmente los secretos del despliegue con npm run generate-secrets. El valor OWNER_CODE sin aplicar hash, guárdalo directamente en un gestor de contraseñas; pon solo el hash generado, y también el secreto de firma independiente, en el gestor de secretos del host.

Endpoints en ejecución

Licencia y software de terceros

Este proyecto se publica con la Licencia MIT.

No redistribuye la CLI de Agent Mail de Tencent. La construvida en Docker instala el paquete publicado por separado @tencent-qqmail/agently-cli en tiempo de compilación. Ese paquete tiene su propia licencia Apache-2.0. Revisa su licenciay los términos correspondientes de QQ Agent Mail antes de usarlo en producción.