FastMail

Interactúa con el correo electrónico, calendario y contactos de FastMail a través de su API JMAP.

Documentación

Servidor MCP de FastMail

Un servidor de Protocolo de Contexto de Modelo (MCP) para integrarse con la API JMAP de FastMail. Este servidor proporciona herramientas para leer correos electrónicos, buscar, gestionar carpetas y enviar correos a través de FastMail.

🚀 Características

📁 Gestión de Buzones: Listar y encontrar buzones/carpetas
📧 Lectura de Correos: Obtener correos de carpetas específicas con vistas previas
🔍 Búsqueda Avanzada: Buscar por palabra clave, remitente, asunto, rango de fechas, archivos adjuntos
📤 Envío de Correos: Enviar correos con soporte para CC/CCO
🎯 Segmentación de Carpetas: Buscar dentro de carpetas específicas
⚡ Rendimiento Rápido: Utiliza el moderno protocolo JMAP de FastMail

📋 Requisitos Previos

Python 3.8+
Cuenta de FastMail con acceso a la API
Token de API de FastMail (Configuración → Privacidad y Seguridad → Integraciones)

🛠 Instalación

Clonar el repositorio:

git clone <your-repo-url>
cd fastmail-mcp-server

Instalar dependencias:
```
pip install -r requirements.txt
```
Obtener tu token de API de FastMail:
- Inicia sesión en FastMail
- Ve a Configuración → Privacidad y Seguridad → Integraciones
- Crea un nuevo token de API
- Copia el token (comienza con fmu1-)

🚀 Uso

Ejecutar el Servidor

python fastmail_mcp_server.py

El servidor se iniciará y escuchará comandos MCP a través de stdio.

Configuración

Primero, configura tus credenciales de FastMail:

{
  "tool": "configure_fastmail",
  "arguments": {
    "apiToken": "fmu1-your-token-here"
  }
}

Herramientas Disponibles

📁 configure_fastmail

Configura tus credenciales de API de FastMail.

📁 list_mailboxes

Lista todos los buzones con sus nombres, roles y recuentos de correos.

{
  "tool": "list_mailboxes",
  "arguments": {
    "role": "inbox"  // Optional: filter by role
  }
}

🔍 find_mailbox

Encuentra un buzón específico por nombre o rol.

{
  "tool": "find_mailbox", 
  "arguments": {
    "name": "Work",     // Partial matching supported
    "role": "sent"      // Or search by role
  }
}

📧 get_emails

Obtiene correos de un buzón específico.

{
  "tool": "get_emails",
  "arguments": {
    "mailboxId": "mailbox-id-here",  // From list_mailboxes
    "mailboxName": "Inbox",          // Alternative to mailboxId
    "limit": 20,                     // Max emails to fetch
    "includeBody": false             // Include full email body
  }
}

🔍 search_emails

Busca correos con filtrado avanzado.

{
  "tool": "search_emails",
  "arguments": {
    "keyword": "project update",     // Text search
    "from_email": "boss@company.com", // From specific sender
    "subject": "meeting",            // Subject contains
    "mailboxId": "inbox-id",         // Search within folder
    "hasAttachment": true,           // Has attachments
    "after": "2024-01-01",          // Date range
    "before": "2024-12-31",
    "limit": 50,
    "includeBody": false
  }
}

📖 get_email_body

Obtiene el contenido completo del cuerpo de un correo específico.

{
  "tool": "get_email_body",
  "arguments": {
    "emailId": "email-id-here",
    "format": "text"  // "text", "html", or "both"
  }
}

📤 send_email

Envía un correo a través de FastMail.

{
  "tool": "send_email",
  "arguments": {
    "to": ["recipient@example.com"],
    "cc": ["cc@example.com"],        // Optional
    "bcc": ["bcc@example.com"],      // Optional  
    "subject": "Hello from MCP!",
    "body": "This is the email body.",
    "isHtml": false                  // Set to true for HTML emails
  }
}

🔧 Integración con Clientes MCP

Claude Desktop

Añade a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "fastmail": {
      "command": "python",
      "args": ["/path/to/fastmail_mcp_server.py"]
    }
  }
}

Otros Clientes MCP

Este servidor sigue el protocolo MCP estándar y debería funcionar con cualquier cliente compatible con MCP.

🏗 Estructura del Proyecto

fastmail-mcp-server/
├── fastmail_mcp_server.py    # Main server implementation
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Package configuration
├── README.md                # This file
└── examples/                # Example usage scripts
    └── test_server.py       # Test script

🔒 Notas de Seguridad

Seguridad del Token de API: Nunca comprometas tu token de API en el control de versiones
Permisos: El token de API tiene acceso a toda tu cuenta de FastMail
Red: Toda la comunicación utiliza HTTPS con las APIs seguras de FastMail

🐛 Solución de Problemas

Problemas Comunes

Error de Autenticación: Verifica que tu token de API sea correcto y tenga los permisos adecuados
Error de Conexión: Comprueba tu conexión a internet y el estado del servicio de FastMail
Correos Faltantes: Asegúrate de estar buscando en el buzón correcto

Modo de Depuración

Habilita el registro de depuración configurando la variable de entorno:

export MCP_DEBUG=1
python fastmail_mcp_server.py

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Añade pruebas si corresponde
Envía una solicitud de extracción