local-fastmail-mcp

Servidor MCP Local de Fastmail

IMPORTANTE: a partir de abril de 2026, Fastmail tiene su propio servidor MCP oficial. Consulta el anuncio en https://www.fastmail.com/blog/an-mcp-server-for-fastmail/

Voy a archivar este repositorio y te sugiero optar por la opción oficial. Dejo el código en línea como ejemplo de mejores prácticas para usar validación de datos con Zod y desarrollo de MCP stdio en TypeScript.

Un servidor Model Context Protocol alojado localmente que conecta tu cuenta de Fastmail a cualquier asistente de IA compatible con MCP (como Claude Desktop, Cursor o herramientas similares).

Esta integración aprovecha la API JMAP nativa de Fastmail y esquemas estrictamente tipados de TypeScript/Zod para permitir que tu asistente de IA lea, gestione e interactúe con tu bandeja de entrada sin depender de integraciones de webhooks de terceros ni exponer credenciales hacia el exterior.

Capacidades

Una vez conectado, tu asistente de IA puede utilizar las siguientes herramientas:

list_mailboxes

Descubre todas las etiquetas, carpetas y buzones de tu cuenta. Devuelve el ID, nombre, rol, conteos de no leídos/totales y permisos de cada buzón.

list_emails

Consulta correos electrónicos por carpeta, búsqueda de palabras clave o estado de leído/no leído. Admite paginación para conjuntos de resultados grandes.

Parámetro	Tipo	Descripción
mailboxId	string?	Filtrar por un ID de buzón específico (usa list_mailboxes para descubrir IDs)
query	string?	Búsqueda de texto completo en el contenido del correo electrónico
unreadOnly	boolean?	Devolver solo correos electrónicos no leídos
limit	number?	Máximo de resultados por página (predeterminado: 20, máximo: 250)
position	number?	Desplazamiento basado en cero para paginación

La respuesta incluye emails, total, position y hasMore. Para paginar los resultados, incrementa position en limit en cada llamada hasta que hasMore sea false.

read_email

Obtén el contenido completo de un correo electrónico específico por su ID.

Parámetro	Tipo	Descripción
emailId	string	El ID exacto del correo electrónico a leer
textOnly	boolean?	Cuando es true, solo obtiene contenido text/plain, omitiendo HTML. Ideal para boletines y correos con mucho HTML para reducir el tamaño de la respuesta.

send_email

Redacta y envía un nuevo correo electrónico desde tu cuenta de Fastmail.

Parámetro	Tipo	Descripción
to	string	Dirección de correo electrónico de destino
subject	string	Línea de asunto
body	string	Contenido del cuerpo en texto plano

mark_email_read

Marca un correo electrónico específico como leído o no leído.

Parámetro	Tipo	Descripción
emailId	string	El ID exacto del correo electrónico
read	boolean?	true para marcar como leído (predeterminado), false para no leído

move_email

Transfiere un correo electrónico a un buzón/carpeta diferente.

Parámetro	Tipo	Descripción
emailId	string	El ID exacto del correo electrónico a mover
mailboxId	string	El ID del buzón de destino

delete_email

Mueve un correo electrónico al buzón de Papelera.

Parámetro	Tipo	Descripción
emailId	string	El ID exacto del correo electrónico a eliminar

---

Enfoque de Seguridad

Este servidor utiliza exclusivamente transporte stdio — nunca expone un puerto HTTP externo. Las credenciales se almacenan localmente en tu archivo .env o se pasan a través de la configuración de entorno del cliente MCP. Toda la comunicación es directamente entre tu máquina local y los endpoints oficiales de api.fastmail.com/jmap.

---

Instalación y Configuración

1. Requisitos

Asegúrate de tener instalado Node.js (versión 22+ recomendada) y npm en tu máquina local.

2. Configura tu Token de API de Fastmail

1. Inicia sesión en tu cuenta de Fastmail.
2. Ve a Settings -> Privacy & Security -> Connected apps & API tokens.
3. Haz clic en Nuevo Token de API.
4. Nombra el token (por ejemplo, "Servidor MCP de IA").
5. Proporciona al token los siguientes alcances:
   • Email (requerido para leer y listar)
   • Email submission (requerido para enviar correos electrónicos)
6. Copia el token de API generado de forma segura.

3. Configuración del Proyecto Local

Clona el repositorio e instala las dependencias requeridas:

npm install

Copia el archivo de variables de entorno de ejemplo:

cp .env.example .env

Abre .env en tu editor de texto y pega tus credenciales:

FASTMAIL_EMAIL=your_email@fastmail.com
FASTMAIL_API_TOKEN=fmu1-your-secret-token-here

4. Compila el Proyecto

Compila el framework de TypeScript a lógica de ejecución nativa de JavaScript:

npm run build

---

Conexión a un Cliente MCP

Este servidor funciona con cualquier cliente compatible con MCP. A continuación se muestra un ejemplo usando Claude Desktop.

Claude Desktop

1. Abre Claude Desktop y elige Configuración -> Desarrollador -> Editar Configuración Abre claude_desktop_config.json

2. Agrega esto a la sección mcpServers, corrigiendo la ruta al archivo index.js compilado y agregando tus propias credenciales:

{
  "mcpServers": {
    "local-fastmail": {
      "command": "node",
      "args": ["/absolute/path/to/your/local-fastmail-mcp/dist/index.js"],
      "env": {
        "FASTMAIL_EMAIL": "your_email@fastmail.com",
        "FASTMAIL_API_TOKEN": "fmu1-your-secret-token-here"
      }
    }
  }
}

3. Reinicia Claude Desktop. Las nuevas herramientas aparecerán instantáneamente y podrás empezar a escribir "Resume mis 20 correos electrónicos no leídos más recientes".

Para otros clientes MCP, consulta su documentación sobre cómo registrar un servidor local stdio apuntando a dist/index.js con las variables de entorno requeridas.

---

Desarrollo y Pruebas

Este proyecto está construido usando TypeScript, @modelcontextprotocol/sdk y análisis Zod.

Si estás desarrollando nuevas herramientas o haciendo ajustes a las capacidades de Fastmail:

1. Compilación: Asegúrate siempre de ejecutar npm run build después de hacer modificaciones.
2. Pruebas: Ejecuta el arnés de cobertura nativo de Vitest ejecutando:

npm test

¡Las solicitudes de extracción son bienvenidas! Abre primero un issue para discutir lo que te gustaría cambiar. Planeo ser exigente, así que también siéntete libre de hacer un fork y crear tu propia versión.