Servidor MCP de Gmail
Una implementación de servidor de Protocolo de contexto de modelo (MCP) para la integración de la API de Gmail, que permite que los asistentes de IA interactúen con los servicios de Gmail.
Características
Funcionalidad principal
- Operaciones de correo electrónico
- Lista de correos electrónicos con filtrado avanzado
- Leer correos electrónicos específicos con contenido completo
- Crear y enviar nuevos correos electrónicos
- Gestión de borradores
- Crear nuevos borradores
- Lista de borradores existentes
- Leer el borrador del contenido
- Actualizar el contenido del borrador y los destinatarios
- Eliminar borradores
- Operaciones del calendario
- Lista de próximos eventos del calendario
- Lea la información detallada del evento
- Crear nuevos eventos de calendario
- Filtrado y búsqueda de eventos
- Compatibilidad con zonas horarias
- Compatibilidad con sincronización de calendario de iOS
Búsqueda y filtrado
- Compatibilidad con consultas de búsqueda de Gmail
- Filtrado basado en etiquetas
- Límites de resultados personalizables
- Capacidades de búsqueda de eventos del calendario
Seguridad
- Integración con Google OAuth2.0
- Gestión segura de credenciales
- Manejo de tokens de actualización
- Soporte de autorización de múltiples ámbitos
Inicio rápido
Prerrequisitos
- Node.js (v14 o superior)
- npm (v6 o superior)
- Cuenta de Google Cloud Platform con las API de Gmail y Calendario habilitadas
- Credenciales OAuth 2.0 con alcances adecuados
Instalación
- Clonar e instalar dependencias:
git clone [repository-url]
cd gmail-mcp-server
npm install
- Configurar el entorno:
# Create .env file
cp .env.example .env
# Add your credentials:
GOOGLE_CLIENT_ID="your_client_id"
GOOGLE_CLIENT_SECRET="your_client_secret"
REDIRECT_URI="http://localhost:4100/code"
GOOGLE_REFRESH_TOKEN="your_refresh_token"
- Construir y ejecutar:
Desarrollo
Scripts disponibles
npm run dev : compila y ejecuta con modo de vigilancianpm run build - Construir el proyectonpm run clean : limpieza de artefactos de compilaciónnpm run watch - Esté atento a los cambios
Estructura del proyecto
gmail-mcp-server/
├── src/
│ ├── config/ # Configuration and setup
│ ├── services/ # Core business logic
│ │ ├── gmail/ # Gmail services
│ │ └── calendar/ # Calendar services
│ ├── tools/ # MCP tool implementations
│ │ ├── calendar/ # Calendar tools
│ │ ├── drafts/ # Draft management tools
│ │ └── messages/ # Email tools
│ ├── types/ # TypeScript definitions
│ └── index.ts # Server entry point
├── dist/ # Compiled JavaScript
└── tests/ # Test files (pending)
Interfaz API
Lista de mensajes
listEmails({
maxResults?: number, // Default: 10
query?: string, // Gmail search query
labelIds?: string[], // Filter by labels
verbose?: boolean // Include details
})
Leer mensaje
readEmail({
messageId: string // Message ID to fetch
})
Operaciones de borrador
// List Drafts
listDrafts({
maxResults?: number, // Default: 10
query?: string, // Search query
verbose?: boolean // Include details
})
// Read Draft
readDraft({
draftId: string // Draft ID to fetch
})
// Create Draft
draftEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean
})
// Update Draft
updateDraft({
draftId: string, // Draft ID to update
to?: string[], // New recipients
cc?: string[], // New CC recipients
bcc?: string[], // New BCC recipients
subject?: string, // New subject
body?: string, // New body content
isHtml?: boolean // Content type flag
})
// Delete Draft
deleteDraft({
draftId: string // Draft ID to delete
})
Enviar correo electrónico
sendEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean,
draftId?: string // Optional: send existing draft
})
Operaciones del calendario
// List Events
listEvents({
maxResults?: number, // Default: 25
timeMin?: string, // Start time (ISO 8601)
timeMax?: string, // End time (ISO 8601)
query?: string, // Text search term
timeZone?: string // Default: Australia/Brisbane
})
// Read Event Details
readEvent({
eventId: string, // Event ID to fetch details
timeZone?: string // Default: Australia/Brisbane
})
// Create Event
createEvent({
summary: string, // Event title
start: {
dateTime: string, // ISO 8601 start time
timeZone?: string // Start time timezone
},
end: {
dateTime: string, // ISO 8601 end time
timeZone?: string // End time timezone
},
description?: string, // Optional event description
location?: string, // Optional event location
attendees?: Array<{ // Optional attendees
email: string,
displayName?: string,
optional?: boolean
}>,
status?: 'confirmed' | 'tentative' | 'cancelled',
sendNotifications?: boolean
})
Manejo de errores
El servidor implementa un manejo integral de errores para:
- Errores de autenticación
- Límites de velocidad de la API
- Solicitudes no válidas
- Problemas de red
- Problemas de sincronización del calendario
- Validación de ID de evento
- Validación de zona horaria
Contribuyendo
Consulte CONTRIBUTING.md para obtener pautas.
Registro de cambios
Consulte CHANGELOG.md para ver el historial de versiones y actualizaciones.
Hoja de ruta
Consulte Backlog.md para conocer las características y mejoras planificadas.
Licencia
Licencia MIT: consulte LICENCIA para obtener más detalles.