Servidor MCP de correo electrónico

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona acceso al correo electrónico a través de IMAP y SMTP. Permite a los agentes de IA y aplicaciones leer, buscar, enviar y gestionar correos electrónicos a través de una interfaz HTTP/SSE estandarizada.

Características

9 herramientas de correo electrónico vía MCP:
- list_folders - Listar todos los buzones/carpetas IMAP
- search_emails - Buscar correos electrónicos con filtros (remitente, asunto, rango de fechas, estado de leído/marcado)
- read_email - Obtener el contenido completo del correo electrónico, incluyendo el cuerpo y los metadatos de los archivos adjuntos
- mark_email - Marcar correos electrónicos como leídos/no leídos o marcados/no marcados
- move_email - Mover correos electrónicos entre carpetas
- send_email - Enviar nuevos correos electrónicos (texto plano o HTML multipart)
- reply_email - Responder a correos electrónicos preservando las cabeceras de hilo
- download_attachment - Descargar archivos adjuntos de correo electrónico al directorio de trabajo
- send_email_with_attachments - Enviar correos electrónicos con archivos adjuntos desde el directorio de trabajo
Arquitectura lista para producción:
- IMAP/SMTP nativo asíncrono con agrupación de conexiones (connection pooling)
- Configuración y validación basadas en Pydantic
- Gestión integral de errores con excepciones estructuradas
- Autenticación mediante clave API a través de la cabecera X-API-Key
- Archivo de servicio systemd para despliegue en Ubuntu
Desarrollo guiado por pruebas (TDD):
- Más de 85 pruebas unitarias y de integración
- 100% de cobertura de la funcionalidad principal
- Servidores de correo simulados para pruebas reproducibles

Instalación con Claude Desktop (Recomendado)

La forma más sencilla de utilizar este servidor es a través del paquete MCPB: una instalación de un solo archivo para Claude Desktop.

1. Descargar

Descargue email_mcp.mcpb desde la versión más reciente.

2. Instalar

Haga doble clic en email_mcp.mcpb. Claude Desktop abrirá un diálogo de instalación.

3. Configurar

Introduzca las credenciales de su servidor de correo cuando se le solicite. Todos los valores se almacenan en el llavero del sistema operativo (Llavero de macOS / Servicio secreto de Linux):

Campo	Descripción	Ejemplo
IMAP Host	Nombre de host del servidor IMAP	`imap.gmail.com`
IMAP Port	Puerto del servidor IMAP	`993` (SSL) · `143` (STARTTLS)
IMAP Username	Su dirección de correo electrónico	`you@example.com`
IMAP Password	Contraseña o contraseña específica de la aplicación	`xxxx xxxx xxxx xxxx`
IMAP SSL	Usar SSL/TLS para IMAP	`true` (puerto 993) · `false` (puerto 143)
SMTP Host	Nombre de host del servidor SMTP	`smtp.gmail.com`
SMTP Port	Puerto del servidor SMTP	`587` (STARTTLS) · `465` (SSL)
SMTP Username	Su dirección de correo electrónico	`you@example.com`
SMTP Password	Contraseña o contraseña específica de la aplicación	`xxxx xxxx xxxx xxxx`
SMTP STARTTLS	Modo STARTTLS	`true` (puerto 587) · `false` · `none` (auto)

Usuarios de Gmail: Debe utilizar una Contraseña de aplicación, no la contraseña habitual de su cuenta de Google. Habilite IMAP en Configuración de Gmail → Reenvío y correo POP/IMAP.

4. Usar

Una vez instalado, Claude puede acceder a su correo electrónico. Pruebe:

"Lista mis correos no leídos de esta semana" "Busca correos de alice@example.com sobre el proyecto" "Envía un correo a bob@example.com con el asunto 'Hola' y el cuerpo '¡Hola Bob!'" "Descarga el primer archivo adjunto del correo con UID 12345" "Envía un correo con el archivo adjunto report.pdf a team@example.com"

Requisitos

Python 3.10+ (se recomienda 3.13)
Acceso a servidor IMAP y SMTP
Clave API para autenticación MCP

Inicio rápido

1. Clonar y configurar

git clone https://github.com/pzanna/email_mcp.git
cd email_mcp
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configurar el entorno

cp .env.example .env
# Edit .env with your credentials

Variables de entorno requeridas:

# IMAP Configuration
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=you@gmail.com
IMAP_PASSWORD=your-app-password
IMAP_SSL=true

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASSWORD=your-app-password
# SMTP_STARTTLS mode: "none" (auto), "true" (force), "false" (disable)
SMTP_STARTTLS=true

# MCP Server Configuration
MCP_API_KEY=your-secret-api-key-here
MCP_HOST=127.0.0.1
MCP_PORT=8420
MCP_SERVER_NAME=email-mcp
MCP_BASE_URL=http://localhost:8420

# Optional
DEFAULT_FROM_NAME=Your Name
MAX_SEARCH_RESULTS=50
IMAP_POOL_SIZE=3

# Attachment Configuration
EMAIL_BASE_DIR=/path/to/workspace
MAX_ATTACHMENT_SIZE_MB=50

3. Ejecutar el servidor

Desarrollo local (Mac/Linux):

source .venv/bin/activate
uvicorn main:app --host 127.0.0.1 --port 8420

Acceder al servidor:

Endpoint MCP: http://localhost:8420/mcp
Comprobación de estado: http://localhost:8420/health
Documentación de la API: http://localhost:8420/docs

Pruebas

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=. --cov-report=html

# Run specific test file
pytest tests/test_integration.py -v

# Run specific test
pytest tests/test_send.py::test_send_email_plain_text -v

Todas las más de 85 pruebas deberían pasar.

Ejemplos de uso

Autenticación

Todos los endpoints MCP requieren la cabecera X-API-Key:

curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8420/mcp/tools

Listar herramientas disponibles

curl -X GET http://localhost:8420/mcp/tools \
  -H "X-API-Key: your-secret-api-key-here"

Buscar correos electrónicos

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "search_emails",
      "arguments": {
        "from": "user@example.com",
        "subject": "invoice",
        "since": "2024-01-01",
        "limit": 10
      }
    }
  }'

Enviar correo electrónico

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": ["recipient@example.com"],
        "subject": "Test Email",
        "body": "This is a test email.",
        "from_name": "My Name"
      }
    }
  }'

Leer correo electrónico

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "read_email",
      "arguments": {
        "uid": "12345",
        "folder": "INBOX"
      }
    }
  }'

Descargar archivo adjunto de correo electrónico

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "download_attachment",
      "arguments": {
        "uid": "12345",
        "attachment_index": 0,
        "folder": "INBOX",
        "filename_override": "renamed_file.pdf"
      }
    }
  }'

Descarga el archivo adjunto a EMAIL_BASE_DIR/attachments/email/downloads/ con validación de seguridad para garantizar que los archivos permanezcan dentro del directorio base.

Enviar correo electrónico con archivos adjuntos

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email_with_attachments",
      "arguments": {
        "to": ["recipient@example.com"],
        "cc": ["manager@example.com"],
        "subject": "Monthly Report",
        "body": "Please find the reports attached.",
        "body_html": "<p>Please find the <strong>reports</strong> attached.</p>",
        "from_name": "John Doe",
        "attachment_paths": [
          "attachments/email/uploads/report1.pdf",
          "attachments/email/uploads/report2.xlsx"
        ]
      }
    }
  }'

Adjunta archivos desde el directorio de trabajo con validación de seguridad completa y aplicación de límites de tamaño.

Gestión de archivos adjuntos

El servidor MCP de correo electrónico proporciona una gestión segura de archivos adjuntos con gestión de archivos basada en el espacio de trabajo.

Estructura del directorio de trabajo

Todas las operaciones de archivos están confinadas al directorio de trabajo configurado:

EMAIL_BASE_DIR/
└── attachments/
    └── email/
        ├── downloads/    # Downloaded email attachments
        └── uploads/      # Files ready to attach to outgoing emails

Características de seguridad

Confinamiento del espacio de trabajo: Todas las operaciones de archivos están restringidas a EMAIL_BASE_DIR
Protección contra recorrido de rutas (Path Traversal): Evita el acceso a archivos fuera del espacio de trabajo
Sanitización de nombres de archivo: Elimina caracteres peligrosos y maneja nombres reservados
Límites de tamaño: Límites configurables por archivo y límites de tamaño total de archivos adjuntos
Validación de tipo de archivo: Asegura que las rutas de los archivos adjuntos apunten a archivos reales

Ejemplos de flujo de trabajo

Flujo de trabajo Descargar → Enviar:

Use download_attachment para guardar archivos adjuntos de correo en downloads/
Mueva o copie archivos a uploads/ según sea necesario
Use send_email_with_attachments para enviar archivos desde uploads/

Flujo de trabajo de carga directa:

Coloque los archivos en el directorio uploads/
Use send_email_with_attachments con rutas relativas al espacio de trabajo

Configuración

# Workspace directory (required for attachment operations)
EMAIL_BASE_DIR=/path/to/your/workspace

# Maximum attachment size per file (default: 50MB)
MAX_ATTACHMENT_SIZE_MB=50

Despliegue

Servidor Ubuntu con systemd

Copiar archivos al servidor:

scp -r email_mcp user@server:/home/user/

Configurar el entorno de Python:

ssh user@server
cd ~/email_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configurar para acceso remoto: Edite .env:

MCP_HOST=0.0.0.0  # Allow remote connections
MCP_BASE_URL=http://<your-server-ip>:8420  # Your server IP

Instalar servicio systemd:

# Edit email-mcp.service to match your paths
sudo cp email-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable email-mcp
sudo systemctl start email-mcp

Comprobar estado:

sudo systemctl status email-mcp
sudo journalctl -u email-mcp -f  # View logs

Configurar cliente MCP

Añada a la configuración de su cliente MCP:

{
  "mcpServers": {
    "email": {
      "url": "http://localhost:8420/mcp",
      "headers": {
        "X-API-Key": "your-secret-api-key-here"
      }
    }
  }
}

Para un servidor remoto, use http://<su-ip-de-servidor>:8420/mcp (reemplace con la IP de su servidor).

Arquitectura

email_mcp/
├── main.py                 # FastAPI application entry point (HTTP/SSE mode)
├── mcp_server.py           # Stdio MCP entry point (MCPB / Claude Desktop mode)
├── config.py               # Pydantic settings (env vars)
├── auth.py                 # API key authentication middleware
├── imap/
│   ├── client.py          # IMAP connection pool
│   ├── read.py            # list_folders, read_email
│   ├── search.py          # search_emails
│   ├── flags.py           # mark_email, move_email
│   └── attachments.py     # download_attachment
├── smtp/
│   ├── client.py          # send_email, reply_email
│   └── attachments.py     # send_email_with_attachments
├── tools/
│   ├── definitions.py     # MCP tool schemas
│   ├── handlers.py        # Tool request routing
│   └── mcp_routes.py      # MCP HTTP endpoints
├── utils/
│   └── attachment_utils.py # Secure file handling utilities
└── tests/                  # 85+ unit and integration tests

Patrones de diseño clave

Agrupación de conexiones: asyncio.Semaphore limita las conexiones IMAP simultáneas (predeterminado: 3)
Gestión de errores: Las excepciones estructuradas se asignan a respuestas de error de MCP
Hilos de correo electrónico: Cabeceras In-Reply-To y References para cadenas de respuesta
Mensajes multipart: Recorre el árbol de mensajes para extraer texto/HTML/archivos adjuntos
Sin transferencia binaria: Los archivos adjuntos devuelven solo metadatos (nombre de archivo, tamaño, content_type)

Solución de problemas

Configuración específica de Gmail

Habilitar IMAP: Configuración → Reenvío y correo POP/IMAP → Habilitar IMAP
Contraseña de aplicación: Use una Contraseña de aplicación en lugar de su contraseña habitual
Gmail SMTP: Use smtp.gmail.com:587 con STARTTLS

Problemas de conexión

# Test IMAP connection
openssl s_client -connect imap.gmail.com:993

# Test SMTP connection
openssl s_client -starttls smtp -connect smtp.gmail.com:587

Errores comunes

CONNECTION_TIMEOUT: Compruebe IMAP_HOST e IMAP_PORT
AUTH_FAILED: Verifique las credenciales, use la contraseña de aplicación para Gmail
FOLDER_NOT_FOUND: Los nombres de las carpetas distinguen entre mayúsculas y minúsculas (use list_folders para verificar)
MESSAGE_NOT_FOUND: El UID puede ser inválido o el mensaje fue eliminado

SMTPException - Connection already using TLS: Establezca SMTP_STARTTLS=none en .env para el modo automático. Los valores válidos son none, true y false.

Desarrollo

Estructura del proyecto

imap/ - Cliente y herramientas IMAP (leer, buscar, flags)
smtp/ - Cliente y herramientas SMTP (enviar, responder)
tools/ - Manejadores y esquemas de endpoints MCP
tests/ - Pruebas unitarias y de integración

Ejecución en desarrollo

# Auto-reload on file changes
uvicorn main:app --reload --host 127.0.0.1 --port 8420

# Debug mode with verbose logging
LOG_LEVEL=DEBUG uvicorn main:app --host 127.0.0.1 --port 8420

Añadir nuevas herramientas

Defina modelos Pydantic para entrada/salida en el módulo apropiado
Implemente la función asíncrona con gestión de errores
Añada el esquema de la herramienta a tools/definitions.py
Conecte el despachador en tools/mcp_routes.py
Escriba pruebas siguiendo el enfoque TDD

Licencia

MIT

Contribución

¡Las contribuciones son bienvenidas! Por favor:

Escriba pruebas para todas las nuevas características
Siga el estilo de código existente (black, isort, mypy)
Actualice este README para cambios significativos
Asegúrese de que todas las pruebas pasen antes de enviar PRs

Soporte

Para problemas, preguntas o solicitudes de características, por favor abra un issue en GitHub.