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:
npm run build npm start

Desarrollo

Scripts disponibles

npm run dev : compila y ejecuta con modo de vigilancia
npm run build - Construir el proyecto
npm run clean : limpieza de artefactos de compilación
npm 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.

Gmail MCP Server

Integrations