Fastmail MCP Server

Un servidor de código abierto que otorga a los asistentes de IA acceso completo al correo electrónico, calendarios y contactos de Fastmail a través de JMAP.

GitHub

Documentación

Servidor MCP de Fastmail

Un servidor de Model Context Protocol (MCP) para Fastmail. Permite que cualquier asistente de IA compatible con MCP lea, busque, envíe y gestione correos electrónicos, calendarios y contactos en una cuenta de Fastmail mediante el protocolo JMAP.

Requisitos previos

Node.js 18 o posterior
Una cuenta de Fastmail (plan Standard o Professional)
Un token de API de Fastmail con acceso JMAP

Configuración

1. Generar un token de API de Fastmail

Inicia sesión en Fastmail
Ve a Configuración → Privacidad y seguridad → Administrar tokens de API
Haz clic en Nuevo token de API
Concede acceso a Correo, Calendarios y Contactos (lectura y escritura)
Copia el token generado

2. Instalación

npm install @jordonh19/fastmail-mcp-server

O ejecuta directamente:

npx @jordonh19/fastmail-mcp-server

3. Configuración

Este servidor MCP funciona con cualquier asistente de IA que admita el Model Context Protocol. A continuación se muestran ejemplos para clientes MCP populares.

Claude Desktop

Añade a tu configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": ["@jordonh19/fastmail-mcp-server"],
      "env": {
        "FASTMAIL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Claude Code CLI

export FASTMAIL_API_TOKEN="your-api-token-here"
claude mcp add fastmail -- npx @jordonh19/fastmail-mcp-server

Cursor

Añade a tu configuración de MCP de Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": ["@jordonh19/fastmail-mcp-server"],
      "env": {
        "FASTMAIL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Windsurf

Añade a tu configuración de MCP de Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": ["@jordonh19/fastmail-mcp-server"],
      "env": {
        "FASTMAIL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

VS Code

Añade a tu configuración de MCP de VS Code (.vscode/mcp.json):

{
  "servers": {
    "fastmail": {
      "command": "npx",
      "args": ["@jordonh19/fastmail-mcp-server"],
      "env": {
        "FASTMAIL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Otros clientes MCP

Para cualquier cliente compatible con MCP, ejecuta el servidor con la variable de entorno FASTMAIL_API_TOKEN configurada:

FASTMAIL_API_TOKEN="your-api-token-here" npx @jordonh19/fastmail-mcp-server

El servidor se comunica a través de stdio por defecto, siguiendo el protocolo de transporte estándar de MCP. Para ejecutarlo a través de HTTP en su lugar, usa la bandera --transport:

FASTMAIL_API_TOKEN="your-api-token-here" npx @jordonh19/fastmail-mcp-server --transport http --port 3000

Herramientas

Correo electrónico

search_emails: Busca correos electrónicos por buzón, texto, remitente, rango de fechas, adjuntos y más.
get_email: Obtén el contenido completo de un correo electrónico por ID.
get_email_headers: Obtén los encabezados seleccionados de un correo electrónico sin devolver el cuerpo completo del mensaje.
get_thread: Obtén todos los correos electrónicos de un hilo de conversación.
get_unread_emails: Recupera rápidamente los correos electrónicos no leídos, opcionalmente filtrados por buzón.
get_latest_emails: Obtén los correos electrónicos más recientes de todos los buzones o de un buzón específico.
get_mailbox_emails: Lista los correos electrónicos en un buzón específico con paginación.
get_email_attachments: Lista los adjuntos de un correo electrónico sin devolver el cuerpo completo del mensaje.
send_email: Redacta y envía un nuevo correo electrónico.
reply_email: Responde o responde a todos en un correo electrónico.
forward_email: Reenvía un correo electrónico a nuevos destinatarios.
create_draft: Guarda un correo electrónico como borrador sin enviarlo.
send_draft: Envía un borrador de correo electrónico previamente guardado.
move_email: Mueve un correo electrónico a un buzón diferente.
add_labels: Añade etiquetas de buzón a un correo electrónico conservando las asignaciones de buzón existentes.
remove_labels: Elimina etiquetas de buzón de un correo electrónico conservando otras asignaciones de buzón.
update_email_flags: Marca correos electrónicos como leídos/no leídos o marcados/no marcados.
delete_email: Mueve a la papelera o elimina permanentemente.
bulk_email_action: Realiza acciones en múltiples correos electrónicos a la vez.
bulk_add_labels: Añade etiquetas de buzón a múltiples correos electrónicos a la vez.
bulk_remove_labels: Elimina etiquetas de buzón de múltiples correos electrónicos a la vez.
archive_email: Mueve uno o más correos electrónicos al buzón de archivo.
mark_mailbox_read: Marca todos los correos electrónicos de un buzón como leídos.
get_mailbox_stats: Obtén recuentos compactos a nivel de buzón de no leídos, correos electrónicos y hilos.
get_account_summary: Obtén una vista general compacta de la cuenta con totales únicos de correos electrónicos y buzones principales.
download_attachment: Descarga un adjunto de correo electrónico por ID de blob.
one_click_unsubscribe: Envía una solicitud de baja con un solo clic para un correo electrónico.

Buzón

list_mailboxes: Lista todos los buzones o carpetas con roles y recuentos de correos electrónicos.
create_mailbox: Crea un nuevo buzón o carpeta.
rename_mailbox: Renombra un buzón o carpeta existente.
delete_mailbox: Elimina un buzón o carpeta, opcionalmente con eliminación forzada.

Calendario

list_calendars: Lista todos los calendarios con nombres, colores y visibilidad.
get_calendar_events: Busca o lista eventos de calendario por rango de fechas, calendario o título.
get_calendar_event: Obtén los detalles completos de un evento de calendario específico.
create_calendar_event: Crea un nuevo evento de calendario con ubicación, participantes y alertas.
update_calendar_event: Actualiza un evento de calendario existente.
delete_calendar_event: Elimina un evento de calendario.

Contactos

list_address_books: Lista todas las libretas de direcciones o grupos de contactos.
search_contacts: Busca contactos por nombre, correo electrónico u otros criterios.
get_contact: Obtén los detalles completos de un contacto específico.
create_contact: Crea un nuevo contacto con correo electrónico, teléfono, organización y más.
update_contact: Actualiza la información de un contacto existente.
delete_contact: Elimina un contacto.

Identidad

get_identities: Lista las identidades de remitente disponibles.

Diagnóstico

check_function_availability: Comprueba qué grupos de funciones de Fastmail y capacidades del cliente MCP están disponibles, con orientación de configuración para accesos faltantes.

Modos de transporte

El servidor admite dos modos de transporte:

stdio (predeterminado)

Transporte de entrada/salida estándar. Utilizado por la mayoría de los clientes MCP (Claude Desktop, Cursor, VS Code, etc.):

FASTMAIL_API_TOKEN="your-token" npx @jordonh19/fastmail-mcp-server

HTTP (Streamable HTTP)

Se ejecuta como un servidor HTTP para acceso remoto o escenarios con múltiples clientes:

FASTMAIL_API_TOKEN="your-token" npx @jordonh19/fastmail-mcp-server --transport http --port 3000

El transporte HTTP expone un único endpoint /mcp que admite el protocolo MCP Streamable HTTP.

Panel web

Cuando se ejecuta en modo HTTP, un panel web integrado está disponible en la raíz del servidor. Proporciona:

Registro de llamadas a herramientas en vivo — ve cada invocación de herramienta MCP en tiempo real a través de SSE
Seguimiento de conexiones — monitoriza las conexiones activas de clientes MCP
Tiempo de actividad del servidor — estado de salud de un vistazo

Al iniciar, el servidor imprime un token de acceso de un solo uso en la consola. Abre http://localhost:<port>/ en un navegador e introduce el token para iniciar sesión. El token está vinculado a una cookie HttpOnly, por lo que nunca aparece en las URLs.

Extensión de Claude Desktop (DXT)

Se puede crear una extensión .dxt preempaquetada para instalación con un clic en Claude Desktop:

npm run build:dxt

Esto produce fastmail-mcp-server-v<version>.dxt en la raíz del proyecto. Haz doble clic en el archivo (o arrástralo a Claude Desktop) para instalarlo. Claude te solicitará tu token de API de Fastmail en el primer uso.

Configuración

El servidor se puede configurar mediante variables de entorno o un archivo de configuración JSON.

Variables de entorno

FASTMAIL_API_TOKEN: Obligatorio. Token de API de Fastmail con acceso JMAP.

Archivo de configuración

Crea un archivo .fastmail-mcp.json en la raíz de tu proyecto o en tu directorio personal:

{
  "transport": "stdio",
  "port": 3000
}

El servidor busca archivos de configuración en este orden:

./.fastmail-mcp.json (directorio actual)
~/.fastmail-mcp.json (directorio personal)

Las variables de entorno y las banderas de la CLI siempre tienen prioridad sobre los valores del archivo de configuración.

Desarrollo

Consulta CONTRIBUTING.md para obtener pautas detalladas de desarrollo.

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

Scripts

Comando	Descripción
`npm run build`	Compilación de TypeScript
`npm run build:dxt`	Compilación + empaquetado como extensión `.dxt` de Claude Desktop
`npm run dev`	Compilación en modo de observación
`npm test`	Ejecuta las pruebas (Vitest)
`npm run test:coverage`	Pruebas con cobertura v8
`npm run typecheck`	Verificación de tipos sin emitir

Ejecuta localmente:

FASTMAIL_API_TOKEN="your-token" node dist/index.js

Licencia

MIT