Fastmail

Interactúa con los datos de correo electrónico, contactos y calendario de Fastmail utilizando la API de Fastmail.

GitHub
131

Documentación

Servidor MCP de Fastmail (No oficial)

Un servidor no oficial del Model Context Protocol (MCP) que proporciona acceso a la API de Fastmail, permitiendo que los asistentes de IA interactúen con datos de correo electrónico, contactos y calendario.

Aviso legal: Este es un proyecto de la comunidad. No está afiliado, respaldado ni soportado por Fastmail. "Fastmail" es una marca comercial de Fastmail Pty Ltd; se utiliza aquí únicamente para describir la compatibilidad con sus APIs públicas JMAP/CalDAV/WebDAV. Úselo bajo su propio riesgo según los términos de la licencia del proyecto.

Características

Operaciones principales de correo electrónico

  • Listar buzones y obtener estadísticas de buzones
  • Listar, buscar y filtrar correos electrónicos con criterios avanzados
  • Obtener correos específicos por ID con contenido completo
  • Enviar correos (texto y HTML) con manejo adecuado de borradores/enviados
  • Responder a correos con el hilo adecuado (cabeceras In-Reply-To, References)
  • Crear, editar y enviar borradores de correo (con o sin hilo)
  • Gestión de correos: marcar como leído/no leído, eliminar, mover entre carpetas

Funciones avanzadas de correo electrónico

  • Manejo de adjuntos: Listar, descargar y enviar adjuntos; guardar adjuntos directamente en el almacenamiento en la nube WebDAV
  • Herramientas de metadatos eficientes en privacidad: Variantes solo de metadatos de las herramientas de listar/buscar/hilos (sin contenido del cuerpo)
  • Soporte de hilos: Obtener hilos de conversación completos
  • Búsqueda avanzada: Filtrado por múltiples criterios (remitente, rango de fechas, adjuntos, estado de lectura)
  • Operaciones masivas: Procesar múltiples correos simultáneamente
  • Estadísticas y análisis: Resúmenes de cuenta y estadísticas de buzones

Operaciones de contactos

  • Listar todos los contactos con información completa de contacto
  • Obtener contactos específicos por ID
  • Buscar contactos por nombre o correo electrónico
  • Crear, actualizar y eliminar contactos (JMAP ContactCard/set; requiere un token de API con alcance de lectura-escritura de contactos)

Operaciones de calendario

  • Listar, obtener, crear, actualizar y eliminar eventos de calendario (a través de CalDAV)
  • Eventos de día completo y con hora, participantes, actualizaciones con reconocimiento de recurrencia

Operaciones de etiqueta vs. mover

  • move_email/bulk_move: Reemplaza TODOS los buzones de un correo (comportamiento de carpeta)
  • add_labels/remove_labels: Añade/elimina buzones ESPECÍFICOS conservando los demás (comportamiento de etiqueta)

Gestión de identidad y cuenta

  • Listar identidades de envío disponibles
  • Resumen de cuenta con estadísticas completas

Configuración

Requisitos previos

  • Node.js 20+
  • Una cuenta de Fastmail con acceso a la API
  • Token de API de Fastmail

Instalación

  1. Clone o descargue este repositorio

  2. Instale las dependencias:

    npm install

  3. Compile el proyecto:

    npm run build

Configuración

  1. Obtenga su token de API de Fastmail:

    • Inicie sesión en la interfaz web de Fastmail
    • Vaya a Configuración → Privacidad y seguridad
    • Busque la sección "Aplicaciones conectadas y tokens de API"
    • Haga clic en "Gestionar tokens de API"
    • Haga clic en "Nuevo token de API"
    • Copie el token generado

  2. Establezca las variables de entorno:

    export FASTMAIL_API_TOKEN="your_api_token_here"
# Optional: customize base URL (defaults to https://api.fastmail.com)
# Only api.fastmail.com and www.fastmailusercontent.com are accepted by default,
# each with an optional regional prefix (phl.api.fastmail.com,
# phl-www.fastmailusercontent.com) as returned by JMAP session discovery.
# For self-hosted JMAP servers, also set FASTMAIL_ALLOW_UNSAFE_BASE_URL=true.
export FASTMAIL_BASE_URL="https://api.fastmail.com"
# Optional: customize attachment download directory (defaults to ~/Downloads/fastmail-mcp/).
# download_attachment savePaths are confined to this directory; set it to the root
# you want attachments saved under to write there directly in one step.
export FASTMAIL_DOWNLOAD_DIR="/path/to/your/downloads"

Ejecutar el servidor

Inicie el servidor MCP:

npm start

Para desarrollo con recarga automática:

npm run dev

Ejecutar desde un clon

git clone https://github.com/MadLlama25/fastmail-mcp && cd fastmail-mcp
npm install && npm run build
FASTMAIL_API_TOKEN="your_token" node dist/index.js

Nota: npx github:MadLlama25/fastmail-mcp no funciona en npm 10 (un error conocido de npm GitFetcher). Use el clon anterior, o instale la Extensión de escritorio empaquetada.

Instalar como Extensión de Escritorio de Claude (DXT)

Puede instalar este servidor como una Extensión de Escritorio para Claude Desktop usando el archivo .dxt empaquetado.

  1. Compile y empaquete:

    npm run build
npx @anthropic-ai/dxt pack

    Esto produce fastmail-mcp.dxt en la raíz del proyecto.

  2. Instale en Claude Desktop:

    • Abra el archivo .dxt, o arrástrelo a Claude Desktop
    • Cuando se le solicite:
      • Token de API de Fastmail: pegue su token (almacenado cifrado por Claude) — obligatorio
      • URL base de Fastmail: déjelo en blanco para usar https://api.fastmail.com (predeterminado)
      • Directorio de descargas: déjelo en blanco para ~/Downloads/fastmail-mcp/
      • Usuario / Contraseña / Nombre para mostrar de CalDAV: opcional — obligatorio para las herramientas de calendario (use una contraseña específica de la aplicación; consulte Soporte de calendario CalDAV)
      • URL / Usuario / Contraseña de WebDAV: opcional — obligatorio para save_attachment_to_webdav (consulte Almacenamiento de archivos WebDAV)

  3. Use cualquiera de las herramientas (p. ej. get_recent_emails).

Herramientas disponibles (52 en total)

Forma de respuesta de las herramientas de listar/buscar: las herramientas de consulta (list_emails, list_emails_metadata, search_emails, search_emails_metadata, get_recent_emails, advanced_search, advanced_search_metadata, list_contacts, search_contacts) devuelven un sobre JSON {"total", "items"} — total es el recuento de coincidencias informado por el servidor, items la página devuelta. Cuando el servidor no informa un total, se devuelve una matriz simple.

🎯 Herramientas más populares:

  • check_function_availability: Compruebe qué está disponible y obtenga orientación de configuración
  • test_bulk_operations: Pruebe de forma segura las operaciones masivas con modo de ejecución en seco
  • send_email: Envío de correos con todas las funciones y manejo adecuado de borradores/enviados
  • advanced_search: Potente filtrado de correos por múltiples criterios
  • get_recent_emails: Acceso rápido a los correos recientes de cualquier buzón

Herramientas de correo electrónico

  • list_mailboxes: Obtenga todos los buzones de su cuenta. En cuentas con muchos buzones, la salida completa puede ser grande — pase properties para una vista reducida.
    • Parámetros: properties (matriz opcional de campos a devolver), parentId (opcional; solo hijos de este buzón, null para el nivel superior)
  • get_mailbox_by_name: Busque un buzón por su ruta completa desde la raíz (p. ej. Inbox/Receipts)
    • Parámetros: path (obligatorio)
  • create_mailbox: Cree un nuevo buzón (carpeta/etiqueta)
    • Parámetros: name (obligatorio), parentId (opcional, omita o use null para el nivel superior)
  • list_emails: Liste correos de un buzón específico o de todos los buzones
    • Parámetros: mailboxId (opcional), limit (predeterminado: 20, máximo: 100), ascending (opcional, primero los más antiguos)
  • list_emails_metadata: Liste correos de un buzón, solo metadatos (cabeceras, sin contenido del cuerpo)
    • Parámetros: mailboxId (opcional), limit (predeterminado: 20, máximo: 100), ascending (opcional, primero los más antiguos)
  • get_email: Obtenga un correo específico por ID
    • Parámetros: emailId (obligatorio)
  • get_email_metadata: Obtenga solo los metadatos de un correo específico (cabeceras en lista blanca, sin cuerpo)
    • Parámetros: emailId (obligatorio)
  • send_email: Envíe un correo (admite hilos mediante las cabeceras opcionales inReplyTo y references)
    • Parámetros: to (obligatorio — matriz o cadena separada por comas), cc (matriz opcional), bcc (matriz opcional), from (opcional), mailboxId (opcional), subject (obligatorio), textBody (opcional), htmlBody (opcional), inReplyTo (matriz opcional), references (matriz opcional), replyTo (matriz opcional), attachments (matriz opcional — consulte Adjuntos de correo al enviar)
  • reply_email: Responda a un correo existente con cabeceras de hilo adecuadas (construye automáticamente In-Reply-To y References). Establezca send=false para guardar como borrador en lugar de enviar.
    • Parámetros: originalEmailId (obligatorio), to (matriz opcional, por defecto el remitente original), cc (matriz opcional), bcc (matriz opcional), from (opcional), textBody (opcional), htmlBody (opcional), send (booleano opcional, predeterminado: true), replyTo (matriz opcional), attachments (matriz opcional — consulte Adjuntos de correo al enviar)
  • create_draft: Cree un borrador de correo (se requiere al menos uno de para/asunto/cuerpo/adjuntos; admite cabeceras de hilo para borradores de respuesta)
    • Parámetros: to (matriz opcional), cc (matriz opcional), bcc (matriz opcional), from (opcional), mailboxId (opcional), subject (opcional), textBody (opcional), htmlBody (opcional), replyTo (matriz opcional), inReplyTo (matriz opcional), references (matriz opcional), attachments (matriz opcional — consulte Adjuntos de correo al enviar)
  • edit_draft: Edite un borrador existente en su lugar — solo cambian los campos proporcionados; los adjuntos existentes se conservan
    • Parámetros: emailId (obligatorio), to, cc, bcc, from, subject, textBody, htmlBody, replyTo, attachments (todos opcionales)
  • send_draft: Envíe un borrador existente
    • Parámetros: emailId (obligatorio)
  • search_emails: Busque correos por contenido
    • Parámetros: query (obligatorio), limit (predeterminado: 20, máximo: 100), ascending (opcional, primero los más antiguos), excludeDrafts (opcional, omitir mensajes de borrador)
    • Los borradores están incluidos por defecto. Establezca excludeDrafts: true para filtrarlos en el servidor.
    • Busca en todos los buzones, incluidos Papelera y Spam. Para flujos de limpieza/verificación, excluya el buzón de Papelera explícitamente (p. ej. advanced_search con excludeMailboxIds) en lugar de confiar en un recuento de búsqueda simple.
  • get_recent_emails: Obtenga los correos más recientes (inspirado en el top-ten de JMAP-Samples)
    • Parámetros: limit (predeterminado: 10, máximo: 50), mailboxName (opcional), ascending (opcional, primero los más antiguos)
    • Cuando se omite mailboxName, se buscan todos los buzones excepto Papelera y Spam. Pase un nombre de buzón (p. ej. 'inbox', 'sent') para limitar a una carpeta.
  • search_emails_metadata: Busque correos por contenido, devolviendo solo metadatos
    • Parámetros: query (obligatorio), limit (predeterminado: 20, máximo: 100), ascending (opcional, primero los más antiguos)
  • mark_email_read: Marque un correo como leído o no leído
    • Parámetros: emailId (obligatorio), read (predeterminado: true)
  • pin_email: Fije o desfije un correo
    • Parámetros: emailId (obligatorio), pinned (predeterminado: true)
  • archive_email: Archive un correo — lo mueve y lo marca como leído en un solo paso atómico
    • Parámetros: emailId (obligatorio), targetMailboxId (obligatorio)
  • delete_email: Elimine un correo (mover a la papelera)
    • Parámetros: emailId (obligatorio)
  • move_email: Mueva un correo a un buzón diferente (reemplaza todos los buzones)
    • Parámetros: emailId (obligatorio), targetMailboxId (obligatorio)
  • add_labels: Añada etiquetas (buzones) a un correo sin eliminar las existentes
    • Parámetros: emailId (obligatorio), mailboxIds (matriz obligatoria)
  • remove_labels: Elimine etiquetas específicas (buzones) de un correo
    • Parámetros: emailId (obligatorio), mailboxIds (matriz obligatoria)

Funciones avanzadas de correo electrónico

  • get_email_attachments: Obtener lista de adjuntos de un correo electrónico
    • Parámetros: emailId (obligatorio)
  • download_attachment: Descargar un adjunto de correo. Si se proporciona savePath, guarda el archivo en disco y devuelve la ruta y el tamaño del archivo. De lo contrario, devuelve una URL de descarga.
    • Parámetros: emailId (obligatorio), attachmentId (obligatorio), savePath (opcional)
    • savePath puede ser absoluta o relativa. Las rutas relativas (incluido un nombre de archivo simple) se resuelven contra el directorio de descarga, por lo que un adjunto llega allí en un solo paso. Las rutas absolutas deben estar dentro de ese directorio; se rechaza el escape por traversal o symlink fuera de él. Para guardar directamente en tu propia ubicación, establece FASTMAIL_DOWNLOAD_DIR a esa raíz: el confinamiento permanece activo, limitado al directorio que elijas.
  • save_attachment_to_webdav: Guardar un adjunto directamente en almacenamiento en la nube WebDAV (Fastmail Files, Nextcloud, ...) sin tocar el disco local
    • Parámetros: emailId (obligatorio), attachmentId (obligatorio), remotePath (obligatorio, relativo), overwrite (por defecto false), createParents (por defecto true)
    • El servidor de almacenamiento y las credenciales provienen de la configuración de entorno FASTMAIL_WEBDAV_*; la herramienta solo elige la ruta relativa debajo de esa base. Los archivos existentes nunca se reemplazan a menos que overwrite: true.
  • advanced_search: Búsqueda avanzada de correos con múltiples criterios
    • Parámetros: query (opcional), from (opcional), to (opcional), subject (opcional), hasAttachment (opcional), isUnread (opcional), isPinned (opcional), mailboxId (opcional), requiredMailboxIds (array opcional — el correo debe estar en TODOS estos), excludeMailboxIds (array opcional — excluir correos en cualquiera de estos), after (opcional), before (opcional), limit (por defecto: 50, máximo: 100), ascending (opcional, más antiguos primero)
    • Al igual que search_emails, busca en todas las bandejas, incluidos Papelera y Spam — delimita con mailboxId/excludeMailboxIds cuando eso importe. (get_recent_emails es el que excluye Papelera/Spam por defecto.)
  • advanced_search_metadata: Mismos filtros que advanced_search, resultados solo de metadatos (sin contenido del cuerpo)
  • get_thread: Obtener todos los correos en un hilo de conversación
    • Parámetros: threadId (obligatorio), includeDrafts (opcional, incluir borradores en progreso)
    • Los mensajes de borrador están excluidos por defecto (una respuesta en progreso es ruido al leer una conversación). Establece includeDrafts: true para incluirlos. Los borradores se identifican por la palabra clave $draft, por lo que la asimetría con search_emails (que incluye borradores por defecto) es deliberada: una búsqueda aún debería encontrar todo lo que has escrito.
  • get_thread_metadata: Obtener todos los correos en un hilo, solo metadatos. También acepta un ID de correo y resuelve su hilo padre.
    • Parámetros: threadId (obligatorio), includeDrafts (opcional)

Estadísticas y Análisis de Correo

  • get_mailbox_stats: Obtener estadísticas de una bandeja (recuento de no leídos, total de correos, etc.)
    • Parámetros: mailboxId (opcional, por defecto todas las bandejas)
  • get_account_summary: Obtener resumen general de la cuenta con estadísticas

Operaciones Masivas

  • bulk_mark_read: Marcar múltiples correos como leídos/no leídos
    • Parámetros: emailIds (array obligatorio), read (por defecto: true)
  • bulk_pin: Fijar o desfijar múltiples correos
    • Parámetros: emailIds (array obligatorio), pinned (por defecto: true)
  • bulk_move: Mover múltiples correos a una bandeja
    • Parámetros: emailIds (array obligatorio), targetMailboxId (obligatorio)
  • bulk_delete: Eliminar múltiples correos (mover a papelera)
    • Parámetros: emailIds (array obligatorio)
  • bulk_add_labels: Añadir etiquetas a múltiples correos simultáneamente
    • Parámetros: emailIds (array obligatorio), mailboxIds (array obligatorio)
  • bulk_remove_labels: Eliminar etiquetas de múltiples correos simultáneamente
    • Parámetros: emailIds (array obligatorio), mailboxIds (array obligatorio)

Herramientas de Contactos

  • list_contacts: Listar todos los contactos
    • Parámetros: limit (por defecto: 50, máximo: 200)
  • get_contact: Obtener un contacto específico por ID
    • Parámetros: contactId (obligatorio)
  • search_contacts: Buscar contactos por nombre o correo
    • Parámetros: query (obligatorio), limit (por defecto: 20, máximo: 100)
  • create_contact: Crear un nuevo contacto (requiere alcance de contactos de lectura-escritura en el token de API)
    • Parámetros: name {given, surname, full}, emails [{address, label}], phones [{number, label}], addresses [{full, label}], notes, addressBookId (todos opcionales, pero se requiere un nombre o un correo)
  • update_contact: Actualizar un contacto existente — cada campo proporcionado reemplaza por completo el valor almacenado (emails: [] elimina todos los correos); los campos no especificados no se tocan
    • Parámetros: contactId (obligatorio), mismos campos que crear, expectState (precondición de estado JMAP opcional)
  • delete_contact: Eliminar permanentemente un contacto (no se puede deshacer)
    • Parámetros: contactId (obligatorio), expectState (opcional)

Herramientas de Calendario

  • list_calendars: Listar todos los calendarios
  • list_calendar_events: Listar eventos de calendario (solo campos principales — sin participantes para eficiencia de tokens)
    • Parámetros: calendarId (opcional), startDate (opcional, ISO 8601), endDate (opcional, ISO 8601), limit (por defecto: 50, máximo: 500)
  • get_calendar_event: Obtener un evento de calendario específico por ID. Devuelve organizador y participantes cuando están disponibles.
    • Parámetros: eventId (obligatorio)
  • create_calendar_event: Crear un nuevo evento de calendario. Admite solo fecha (p. ej. 2026-04-01) para eventos de todo el día. DTEND es exclusivo según RFC 5545 — un evento de un día el 1 de abril necesita end: "2026-04-02".
    • Parámetros: calendarId (obligatorio), title (obligatorio), description (opcional), start (obligatorio, ISO 8601 o solo fecha), end (obligatorio, ISO 8601 o solo fecha), location (opcional), participants (array opcional de {email, name?})
  • update_calendar_event: Parchear un evento de calendario existente. Preserva todos los datos existentes (asistentes, recordatorios, reglas de recurrencia, etc.) que no se estén cambiando. Omite un campo para dejarlo sin cambios; pasar una cadena vacía o solo espacios en blanco para title, description o location se rechaza (no dejará la propiedad en blanco silenciosamente). Para eliminar description o location, listalos en clearFields. Los tiempos flotantes (sin Z/offset) preservan la zona horaria original. ADVERTENCIA: proporcionar participants reemplaza TODOS los datos de asistentes existentes; participants: [] elimina todos los asistentes (y el ORGANIZADOR ahora huérfano).
    • Parámetros: eventId (obligatorio), title, description, start, end, location, participants (array de {email, name?}), clearFields (array de "description"/"location" para eliminar), confirmRecurring (booleano)
  • delete_calendar_event: Eliminar un evento de calendario
    • Parámetros: eventId (obligatorio)

Limitaciones conocidas del calendario

  • Eventos recurrentes: Solo se admite la modificación de "todos los eventos" (VEVENT maestro). "Solo este evento" o "este y futuros eventos" no se admiten. Cambiar inicio/fin en eventos recurrentes con excepciones de anulación requiere confirmRecurring: true — las excepciones huérfanas se podan para prevenir errores del servidor.
  • Parámetros de asistentes: RSVP, ROLE, CUTYPE y otros parámetros de asistentes se analizan al leer pero no se pueden establecer al crear/actualizar — solo se aceptan email y name.

Herramientas de Identidad y Pruebas

  • list_identities: Listar identidades de envío (direcciones de correo que se pueden usar para enviar)
  • check_function_availability: Verificar qué funciones están disponibles según los permisos de la cuenta (incluye guía de configuración). Las herramientas de calendario se ejecutan sobre CalDAV, por lo que el calendario se reporta como disponible cuando las credenciales CalDAV están configuradas, independientemente de la capacidad de calendario JMAP.
  • test_bulk_operations: Probar operaciones masivas de forma segura con modo de simulación
    • Parámetros: dryRun (por defecto: true), limit (por defecto: 3)

Información de la API

Este servidor utiliza la API JMAP (JSON Meta Application Protocol) proporcionada por Fastmail. JMAP es una alternativa moderna y eficiente a IMAP para el acceso al correo.

Inspirado en Fastmail JMAP-Samples

Muchas características de este servidor MCP están inspiradas en el repositorio oficial Fastmail JMAP-Samples, incluyendo:

  • Recuperación de correos recientes (basado en el ejemplo de los diez principales)
  • Operaciones de gestión de correos
  • Llamadas de método JMAP encadenadas eficientes

Autenticación

El servidor utiliza autenticación de token portador con la API de Fastmail. Los tokens de API proporcionan acceso seguro sin exponer tu contraseña principal de la cuenta.

Límites de tasa

Fastmail aplica límites de tasa a las solicitudes de API. El servidor maneja la limitación de tasa estándar, pero las solicitudes excesivas pueden ser limitadas.

Soporte de Calendario CalDAV

Fastmail actualmente no expone acceso al calendario a través de tokens de API JMAP — el alcance urn:ietf:params:jmap:calendars no está disponible porque la especificación de Calendarios JMAP sigue siendo un Internet-Draft de la IETF (draft-ietf-jmap-calendars). Fastmail ha declarado que añadirá soporte de calendario JMAP una vez que la especificación se convierta en RFC, pero no hay un cronograma público.

Sin embargo, Fastmail soporta completamente CalDAV para acceso al calendario a través de caldav.fastmail.com. Todas las herramientas de calendario usan CalDAV directamente.

Configuración

  1. Crea una contraseña específica de aplicación en Fastmail:

    • Ve a Configuración → Privacidad y seguridad → Gestionar contraseñas de aplicaciones
    • Crea una nueva contraseña de aplicación (puedes nombrarla "CalDAV MCP" o similar)

  2. Establece las siguientes variables de entorno:

    export FASTMAIL_CALDAV_USERNAME="your-email@fastmail.com"
export FASTMAIL_CALDAV_PASSWORD="your-app-specific-password"
# Optional: display name for ORGANIZER when creating events with participants
export FASTMAIL_CALDAV_DISPLAY_NAME="Your Name"

Cuando estas variables están establecidas, todas las herramientas de calendario están disponibles. Cuando no están establecidas, las herramientas de calendario devolverán un error con instrucciones de configuración.

Almacenamiento de archivos WebDAV (opcional)

save_attachment_to_webdav guarda adjuntos directamente en almacenamiento en la nube. Configura el destino (nunca proporcionado por las herramientas en tiempo de ejecución — esto es deliberado, para que un llamador con mal comportamiento no pueda redirigir cargas):

# Fastmail Files:
export FASTMAIL_WEBDAV_URL="https://myfiles.fastmail.com/"
export FASTMAIL_WEBDAV_USERNAME="your-email@fastmail.com"
export FASTMAIL_WEBDAV_PASSWORD="app-password-with-files-scope"

# ...or any WebDAV server, e.g. Nextcloud:
# export FASTMAIL_WEBDAV_URL="https://cloud.example.com/remote.php/dav/files/USERNAME/"

La URL debe ser HTTPS. Nota: Fastmail Files ignora la precondición WebDAV If-None-Match, por lo que la herramienta realiza una verificación explícita de existencia antes de cargas sin sobrescritura.

Adjuntos de correo al enviar

send_email, create_draft, edit_draft y reply_email aceptan un array attachments. Cada entrada usa exactamente una fuente:

  • { "localPath": "report.pdf" } — un archivo dentro de FASTMAIL_DOWNLOAD_DIR (mismo confinamiento que las descargas)
  • { "emailId": "...", "attachmentId": "..." } — re-adjuntar desde un correo existente (copia cero: no se transfieren bytes)
  • { "blobId": "...", "name": "...", "type": "..." } — un blob JMAP ya cargado

Las cargas respetan el maxSizeUpload del servidor (~50 MB en Fastmail). Editar un borrador preserva sus adjuntos existentes.

Alcance de escritura de contactos

create_contact / update_contact / delete_contact necesitan que el token de API tenga alcance de contactos de lectura-escritura (Configuración → Privacidad y seguridad → Tokens de API). Los tokens de solo lectura mantienen las tres herramientas de lectura funcionando y fallan las escrituras con un error forbidden.

Desarrollo

Estructura del proyecto

src/
├── index.ts               # Main MCP server implementation
├── auth.ts                # Authentication handling
├── jmap-client.ts         # JMAP client wrapper
├── contacts-calendar.ts   # Contacts extensions (JMAP)
├── caldav-client.ts       # CalDAV calendar client (the calendar path — JMAP calendars are not available)
├── webdav-files-client.ts # WebDAV file storage client (save_attachment_to_webdav)
├── url-validation.ts      # Base-URL allowlist / HTTPS validation
├── coerce.ts              # Input coercion helpers
└── *.test.ts              # Unit tests (colocated)

Compilación

npm run build

Modo de desarrollo

npm run dev

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegúrate de que:

  1. El código siga el estilo existente
  2. Todas las funciones estén correctamente tipadas
  3. El manejo de errores esté implementado
  4. La documentación se actualice para nuevas características

Solución de problemas

Problemas comunes

  1. Errores de autenticación: Asegúrate de que tu token de API sea válido y tenga los permisos necesarios
  2. Dependencias faltantes: Ejecuta npm install para asegurarte de que todas las dependencias estén instaladas
  3. Errores de compilación: Verifica que la compilación de TypeScript se complete sin errores usando npm run build
  4. Errores de "Forbidden" en Calendario/Contactos: Usa check_function_availability para ver la guía de configuración

¿Las herramientas de correo fallan con errores de serialización?

Si get_email, list_emails, search_emails o advanced_search fallan con errores de "content serialization" o "Cannot read properties of undefined", actualiza a v1.7.1 o posterior (cualquier versión actual incluye la corrección). Esto fue causado por una validación incompleta de las respuestas JMAP que salió a la luz después de que la actualización del MCP SDK v1.x añadiera una verificación de resultados más estricta.

¿El calendario no funciona?

Las herramientas de calendario funcionan a través de CalDAV, no de JMAP. Si devuelven "CalDAV not configured", establece FASTMAIL_CALDAV_USERNAME y FASTMAIL_CALDAV_PASSWORD (consulta Soporte de calendario CalDAV).

¿Los contactos no funcionan?

Si las funciones de contactos devuelven errores de "Forbidden":

  1. Alcance del token de API: las escrituras (create_contact/update_contact/delete_contact) necesitan alcance de contactos de lectura-escritura (consulta Alcance de escritura de contactos)
  2. Plan de cuenta: la API de contactos puede requerir ciertos planes de Fastmail

Los errores Contact not found / Calendar event not found significan que el ID está desactualizado: vuelve a listar y reintenta.

Solución: Ejecuta check_function_availability para obtener una guía de configuración paso a paso.

Probando tu configuración

Usa las herramientas de prueba integradas:

  • check_function_availability: Ve qué está disponible y obtén ayuda de configuración
  • test_bulk_operations: Prueba operaciones masivas de forma segura sin hacer cambios

Para obtener información de error más detallada, revisa la salida de la consola al ejecutar el servidor.

Privacidad y seguridad

  • Los tokens de API se almacenan cifrados por Claude Desktop cuando se instalan a través del DXT y este servidor nunca los registra.
  • El servidor evita registrar errores sin procesar y datos sensibles (tokens, direcciones de correo, identidades, nombres de archivos adjuntos/blobIds) en los mensajes de error.
  • Las respuestas de las herramientas pueden incluir metadatos/contenido de tu correo por diseño (por ejemplo, al listar correos), pero los identificadores internos y las credenciales no se divulgan más allá de lo que Fastmail devuelve para los datos solicitados.
  • Si encuentras errores, los mensajes se sanitizan y resumen para evitar la filtración de información personal.