MCP Email Server

Gestiona correos electrónicos usando los protocolos Gmail e IMAP. Requiere configuración externa para credenciales y ajustes.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Email Server

Un servidor integral de Model Context Protocol (MCP) para la gestión unificada de correo electrónico, compatible tanto con cuentas de Gmail como de IMAP.

🚀 Características

Compatibilidad con protocolo MCP: Servidor MCP HTTP de transmisión
Integración con Gmail: Acceso a la API de Gmail basado en OAuth2 con gestión automática de tokens
Soporte IMAP: Conexiones IMAP seguras a varios proveedores de correo
Interfaz unificada: Interfaz MCP única para todas las cuentas de correo con detección automática
Gestión de cuentas: Configuración centralizada y prueba de conexión
Manejo robusto de errores: Gestión integral de tiempos de espera y errores con orientación detallada al usuario
Seguridad: Almacenamiento de contraseñas cifradas para cuentas IMAP
Búsqueda entre cuentas: Busca en todas las cuentas configuradas simultáneamente

📋 Herramientas MCP disponibles

🔄 Herramientas unificadas (detección automática del tipo de cuenta)

Herramienta	Descripción	Parámetros
`list_emails`	Obtener lista de correos de cualquier cuenta (detección automática de tipo)	`account_name`, `limit?`, `folder?`, `unread_only?`
`search_emails`	Buscar correos en cualquier cuenta (detección automática de tipo)	`account_name`, `query`, `limit?`
`search_all_emails`	Buscar en todas las cuentas de Gmail e IMAP	`query`, `accounts?`, `limit?`, `sortBy?`
`get_email_detail`	Obtener información detallada de un correo de cualquier cuenta	`account_name`, `email_id`
`archive_email`	Archivar correos en cualquier cuenta (detección automática de tipo)	`account_name`, `email_id`, `remove_unread?`
`send_email`	Enviar correos desde cualquier cuenta (detección automática de tipo)	`account_name`, `to`, `subject`, `text/html`, `cc?`, `bcc?`, `attachments?`

🔧 Herramientas de administración

Herramienta	Descripción	Parámetros
`list_accounts`	Listar cuentas de correo configuradas con estado	Ninguno
`test_connection`	Probar conexión a una cuenta específica	`account_name`
`get_account_stats`	Obtener estadísticas integrales de todas las cuentas	Ninguno

🛠️ Scripts disponibles

Ubicados en el directorio scripts/:

📧 Autenticación y configuración

Script	Propósito	Uso
`gmail-desktop-auth.mjs`	Configuración de autenticación OAuth2 de Gmail	`npx tsx scripts/gmail-desktop-auth.mjs [ACCOUNT_NAME]`
`cleanup-env-tokens.mjs`	Limpieza y estandarización de variables de entorno	`npx tsx scripts/cleanup-env-tokens.mjs`
`setup-xserver.mjs`	Configuración interactiva de cuentas IMAP para XServer	`npx tsx scripts/setup-xserver.mjs`
`encrypt-password.ts`	Cifrado de contraseñas para cuentas IMAP	`npx tsx scripts/encrypt-password.ts [PASSWORD]`

🖥️ Administración del servidor

Script	Propósito	Uso
`server.sh`	Administración de MCP Email Server (iniciar/detener/reiniciar/ver estado)	`./scripts/server.sh {start\|stop\|restart\|status\|logs\|health}`
`monitor-health.ts`	Verificación de salud integral (con diagnóstico del estado de autenticación)	`npm run health:check`
`test-search-all.sh`	Prueba de la función de búsqueda entre cuentas	`./scripts/test-search-all.sh`

⚙️ Instalación y configuración

1. Instalación

git clone <repository-url>
cd mcp-email-server
npm install

2. Configuración del entorno

# 環境設定ファイルのサンプルをコピー
cp .env.example .env

# 設定を編集
nano .env

3. Variables de entorno requeridas

# 必須 - パスワード保存用暗号化キー
EMAIL_ENCRYPTION_KEY=your-unique-32-character-encryption-key

# Gmail OAuth2設定（Gmailを使用する場合）
GMAIL_CLIENT_ID=your-gmail-client-id
GMAIL_CLIENT_SECRET=your-gmail-client-secret  
GMAIL_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob

# Gmailアカウントトークン（OAuthスクリプトで取得）
GMAIL_REFRESH_TOKEN_accountname=your-refresh-token

# IMAPアカウント設定（IMAPを使用する場合）
IMAP_HOST_accountname=mail.example.com
IMAP_USER_accountname=user@example.com
IMAP_PASSWORD_accountname=encrypted-password-here
IMAP_PORT_accountname=993
IMAP_TLS_accountname=true

4. Configuración de cuentas

Cuenta de Gmail

# 最初に.envファイルにGmail OAuth2認証情報を設定し、その後：
node scripts/gmail-desktop-auth.mjs ACCOUNT_NAME

# 認証完了後、サーバーを再起動して設定を反映：
./scripts/server.sh restart

Cuenta IMAP

# 対話式IMAPセットアップ（推奨）：
node scripts/setup-xserver.mjs

# または手動でパスワードを暗号化：
npx tsx scripts/encrypt-password.ts "あなたのパスワード"

5. Inicio y verificación del servidor

# サーバー起動（LaunchAgent使用）
./scripts/server.sh start

# サーバー状態確認
./scripts/server.sh status

# 包括的ヘルスチェック（推奨）
./scripts/server.sh health
# または
npm run health:check

# 完全テストスイート
npm test

🔧 Configuración de MCP

Configuración de MCP en Cursor (recomendado)

Agregar al archivo de configuración de MCP de Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-email-server": {
      "url": "http://localhost:3456/mcp",
      "transport": "http"
    }
  }
}

【Nota】Dado que la conexión se realiza sin autenticación, nunca expongas el servidor públicamente.

🖥️ Servidor y pruebas

Ubicados en el directorio bin/:

Script	Propósito	Uso
`run-streaming-email-server.ts`	Iniciar el servidor MCP de producción	`npx tsx bin/run-streaming-email-server.ts`
※ run-stdio-email-server.ts está en mantenimiento finalizado

Método de inicio permanente en macOS

Dado que es un servidor MCP HTTP de transmisión, opera el servidor con inicio permanente mientras esté en uso. En macOS, es conveniente crear un archivo plist de LaunchAgent como el siguiente. Reemplaza /PATH/TO con la ruta adecuada.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>localhost.mcp-email-server</string>
    <key>Program</key>
    <string>/PATH/TO/tsx</string>
    <key>ProgramArguments</key>
    <array>
        <string>/PATH/TO/.nvm/versions/node/v23.7.0/bin/tsx</string>
        <string>/PATH/TO/mcp-email-server/bin/run-streaming-email-server.ts</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/PATH/TO/src/git/mcp-email-server</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/PATH/TO/Library/Logs/mcp-email-server.log</string>
    <key>StandardErrorPath</key>
    <string>/PATH/TO/Library/Logs/mcp-email-server-error.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/PATH/TO/NODE/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>NODE_PATH</key>
        <string>/PATH/TO/NODE/lib/node_modules</string>
    </dict>
</dict>
</plist>

Iniciar servidor con LaunchAgent

launchctl load ~/Library/LaunchAgents/localhost.mcp-email-server.plist

Otros scripts de prueba están ubicados en el directorio scripts/:

Script	Propósito	Uso
`quick-test.ts`	Prueba rápida de conexión y respuesta	`npx tsx scripts/quick-test.ts`
`monitor-health.ts`	Monitoreo integral de salud	`npx tsx scripts/monitor-health.ts`
`decrypt-test.ts`	Prueba de la función de descifrado de contraseñas	`npx tsx scripts/decrypt-test.ts`

💡 Ejemplos de uso de herramientas MCP

Gestión de cuentas

// 設定済みアカウントを全て一覧表示
mcp_mcp-email-server_list_accounts()

// 特定アカウントの接続テスト
mcp_mcp-email-server_test_connection("business_gmail")

// 全アカウントの包括的統計情報を取得
mcp_mcp-email-server_get_account_stats()

Operaciones de correo

// 全アカウントを横断検索
mcp_mcp-email-server_search_all_emails({
  query: "invoice",
  accounts: "ALL",
  limit: 20,
  sortBy: "date"
})

// 特定アカウントからメール一覧を取得
mcp_mcp-email-server_list_emails({
  account_name: "business_gmail",
  limit: 10,
  unread_only: true
})

// メール送信（Gmail/IMAP自動判定）
mcp_mcp-email-server_send_email({
  account_name: "business_gmail",
  to: "recipient@example.com",
  subject: "会議スケジュール",
  text: "来週の会議のスケジュールを組みましょう。",
  cc: "manager@example.com"
})

// メールをアーカイブ
mcp_mcp-email-server_archive_email({
  account_name: "business_gmail", 
  email_id: "email_id_here"
})

🧪 Pruebas

Este proyecto incluye pruebas integrales diseñadas para funcionar con cualquier configuración de cuentas:

# 完全テストスイート
npm test

# 特定のテストカテゴリ
npm run test:core          # コア機能テスト
npm run test:integration   # 統合テスト
npm run test:imap-timeout  # IMAPタイムアウト防止テスト

# ヘルスモニタリング
npm run health:check       # 包括的ヘルスチェック
npm run test:quick         # 高速接続テスト

Requisitos de prueba

Configuración mínima: Al menos una cuenta de Gmail o una cuenta IMAP configurada
Cobertura completa: Las pruebas completas requieren tanto cuentas de Gmail como de IMAP
Las pruebas detectan automáticamente la configuración de cuentas y se adaptan

🔐 Funciones de seguridad

Cifrado de contraseñas

Todas las contraseñas IMAP se cifran con AES-256-GCM
Se requiere una clave de cifrado única por instalación
Vectores de inicialización aleatorios para mayor seguridad

Seguridad OAuth2

El acceso a Gmail utiliza OAuth2 con rotación de tokens de actualización
No se almacenan credenciales en texto plano
Renovación automática de tokens

Mejores prácticas

Aislamiento de variables de entorno
No incluir credenciales en el control de versiones
Se recomienda rotación periódica de tokens
Solicitar alcances de permisos mínimos

🛠️ Arquitectura

Componentes principales

Manejador de protocolo MCP: Procesamiento de solicitudes conforme a JSON-RPC 2.0
Administrador de cuentas: Configuración y detección centralizada de cuentas
Manejador de Gmail: Operaciones de API de Gmail autenticadas con OAuth2
Manejador de IMAP: Implementación segura del protocolo IMAP con agrupación de conexiones
Interfaz unificada: Detección automática del tipo de cuenta y enrutamiento

Manejo de errores

Respuestas de error integrales conformes a MCP
Orientación detallada al usuario para problemas comunes
Mecanismo automático de reintentos para fallos temporales
Degradación gradual para disponibilidad parcial del servicio

📊 Estado actual

✅ Totalmente operativo (100% de tasa de éxito)

Pruebas y verificación completadas de todas las herramientas tanto en CLI como en entornos MCP:

Gestión de cuentas: 100% de tasa de éxito en todos los tipos de cuenta
Operaciones de correo: Soporte completo de operaciones CRUD
Búsqueda entre cuentas: Búsqueda integrada en Gmail e IMAP
Prueba de conexión: Verificación robusta de conectividad
Manejo de errores: Recuperación integral de errores y orientación al usuario

🎯 Métricas de rendimiento

Tiempo de respuesta: Menos de 5 segundos para la mayoría de las operaciones
Prevención de tiempos de espera: 100% de tasa de éxito en pruebas de tiempo de espera
Detección de cuentas: Detección automática de 7/7 cuentas configuradas
Recuperación de errores: Manejo gradual de problemas de red y autenticación

🔧 Solución de problemas

Para solución de problemas detallada, consulta doc/re-auth.md.

Problemas comunes y flujo de resolución

1. Diagnóstico y resolución de errores de autenticación

# 1. ヘルスチェック実行
npm run health:check

# 2. エラーパターンに応じて対処
# パターンA: Gmail認証エラー
node scripts/gmail-desktop-auth.mjs ACCOUNT_NAME
./scripts/server.sh restart

# パターンB: サーバー再起動のみ必要
./scripts/server.sh restart

# パターンC: IMAP認証エラー
npx tsx scripts/decrypt-test.ts

2. Administración del servidor

# サーバー状態確認
./scripts/server.sh status

# サーバー再起動（認証後は必須）
./scripts/server.sh restart

# ログ確認
./scripts/server.sh logs
./scripts/server.sh logs error

3. Diagnóstico detallado

# 横断検索テスト
./scripts/test-search-all.sh

# 個別アカウントテスト
curl -X POST http://localhost:3456/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"test_connection","arguments":{"account_name":"ACCOUNT_NAME"}}}'

Mantenimiento preventivo

# 定期ヘルスチェック（推奨: 毎日）
./scripts/server.sh health

# 定期再起動（推奨: 週1回）
./scripts/server.sh restart

Modo de depuración

# 詳細ログでサーバー起動
DEBUG=1 npx tsx bin/run-streaming-email-server.ts

# 開発モードで実行
NODE_ENV=development npx tsx bin/run-streaming-email-server.ts

📈 Extensiones futuras

Soporte para proveedores de correo adicionales
Opciones avanzadas de filtrado y búsqueda
Gestión de plantillas de correo
Soporte de operaciones por lotes
Integración de calendario para correos de reuniones

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de funcionalidad
Agrega pruebas integrales
Verifica que todas las pruebas pasen
Envía una solicitud de extracción

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🆘 Soporte

Para problemas o preguntas:

Consulta el flujo de trabajo para IA en doc/re-auth.md
Diagnostica problemas con la verificación de salud: ./scripts/server.sh health
Utiliza las herramientas de administración del servidor: ./scripts/server.sh --help
Revisa los registros de depuración: ./scripts/server.sh logs
Crea un issue con información detallada del error y configuración

🤖 Asistencia con IA

Este proyecto incluye flujos de trabajo de diagnóstico y resolución para IA (Claude, ChatGPT, etc.):

Diagnóstico automático: Clasificación automática de problemas mediante npm run health:check
Resolución gradual: Procedimientos específicos de manejo por patrón
Mantenimiento preventivo: Recomendaciones periódicas de mantenimiento