yandex-calendar-mcp

Un servidor MCP que da a un asistente de IA acceso a Yandex Calendar mediante CalDAV. Lee la agenda, crea, mueve y elimina eventos.

Русская версия

Nota sobre el idioma: las descripciones y respuestas de las herramientas están en ruso, porque el servidor fue escrito para un asistente de habla rusa. El código, la configuración y este documento están en inglés. Todo lo demás funciona independientemente del idioma.

Qué hace

Lectura

• Eventos de cualquier período: hoy por defecto, o un rango explícito de hasta 92 días.

• Todos los calendarios a la vez, con cada evento etiquetado con el calendario del que procede, o un único calendario seleccionado por nombre.

• Eventos recurrentes expandidos en fechas concretas. Si la expansión falla, el evento se devuelve con una advertencia en lugar de presentarse como exacto.

• Asistentes enumerados con cómo ha respondido cada uno: aceptado, rechazado, con reservas o sin responder.

• Los eventos de día completo se reconocen como tales, no se muestran como citas a medianoche.

• Cada respuesta indica la zona horaria y el desplazamiento UTC utilizados.

Escritura

• Crear un evento: título, inicio, fin o duración, ubicación, descripción; con hora o de día completo que abarque varios días.

• Crear un evento recurrente (diario, semanal, mensual o anual) limitado por un número de ocurrencias o por una fecha de fin.

• Actualizar un evento: moverlo, renombrarlo, cambiar la ubicación o la descripción. Solo se tocan los campos que se pasan; un evento movido conserva su duración original salvo que se indique lo contrario.

• Editar o eliminar una sola ocurrencia de una serie recurrente, o la serie completa. Un día cambiado se convierte en una anulación RECURRENCE-ID; un día eliminado, en un EXDATE, los mecanismos estándar, de modo que el resultado se vea correcto en la aplicación de Yandex y en cualquier otro cliente.

• Invitar a personas: los asistentes se pueden añadir al crear un evento, y añadirse o eliminarse más tarde. El propio Yandex envía las invitaciones y cancelaciones por correo.

• Eliminar un evento, con las salvaguardas descritas a continuación.

Zonas horarias, tratadas con cuidado

• Cada marca de tiempo se convierte a la zona configurada con zoneinfo. Las cadenas de hora nunca se cortan por posición de carácter.

• Los eventos escritos llevan un DTSTART;TZID=… explícito más un bloque VTIMEZONE completo, de modo que cualquier cliente de calendario los lea de la misma manera.

• La máquina que ejecuta el servidor suele estar en UTC; eso nunca se filtra en las respuestas, y la zona realmente utilizada se nombra en cada respuesta, de modo que un error sea visible en lugar de silencioso.

Diseñado para que lo maneje un asistente

• Las respuestas son texto plano legible con el uid del evento incluido, de modo que una edición o eliminación pueda seguir directamente a un listado.

• create_event requiere un calendario explícito: la gente tiene varios calendarios para distintos fines, y un evento archivado silenciosamente en el equivocado es un evento perdido. Se espera que el asistente pregunte en lugar de adivinar.

• Los errores vuelven como frases que explican qué hacer a continuación, no como trazas de pila.

Related MCP server: MCP Personal Calendar

Requisitos

• Python 3.10 o superior (probado con 3.13)

• Una contraseña de aplicación de Yandex, no la contraseña de la cuenta: https://id.yandex.ru/security/app-passwords → tipo de aplicación "Календарь (CalDAV)"

pip install -r requirements.txt

tzdata está en los requisitos a propósito: las imágenes slim de Linux a menudo no incluyen una base de datos de zonas horarias, y ZoneInfo("Europe/Moscow") falla entonces.

Configuración

Toda la configuración proviene de variables de entorno.

El servidor habla MCP sobre stdio. Hay un ejemplo de configuración de cliente en examples/.

Herramientas

Eliminar es irreversible: qué te protege

1. Comprobación del título. delete_event recibe tanto el uid como el título del evento. Se comparan; si no coinciden, no se elimina nada y la respuesta nombra ambos títulos y el calendario. Un uid obsoleto o confundido es la forma realista de destruir el evento equivocado, y esto es lo que lo detecta.

2. Papelera. Antes de cada eliminación y de cada actualización, el evento original completo se escribe en YANDEX_TRASH_DIR como archivo .ics con marca de tiempo. Si la copia no se puede escribir, la operación no se ejecuta en absoluto. La recuperación consiste en importar ese archivo de nuevo.

3. Series recurrentes. Cualquier edición o eliminación en una serie debe indicar a qué se aplica: occurrence para un día, apply_to_series para la serie completa. Sin ninguno de los dos, la herramienta se niega y explica la elección. Así se evita que "cancelar el martes" borre un año de reuniones.

Invitar a personas envía correos reales

Yandex anuncia calendar-auto-schedule, por lo que añadir un asistente hace que el servidor envíe una invitación, y eliminarlo envía una cancelación. Ninguna de las dos se puede recuperar. Esto se verificó de extremo a extremo, no solo por las capacidades anunciadas del servidor: una invitación añadida mediante create_event llegó a la bandeja de entrada del destinatario.

Lo que se deriva de esto:

• Las direcciones se toman al pie de la letra y se validan. El servidor nunca deriva una dirección de un nombre: un asistente que recuerde a medias un contacto enviaría un correo a un extraño.

• update_event añade y elimina asistentes en lugar de reemplazar la lista, de modo que se conservan las respuestas ya dadas por los demás.

• Cada respuesta enumera exactamente quién está en el evento y cómo ha respondido, de modo que una dirección incorrecta sea visible de inmediato.

Un asistente que maneje este servidor debe confirmar la lista de direcciones con su usuario antes de llamar. Enviar una invitación no es una acción deshacible.

Pruebas

python tests/write_cycle.py "Calendar name"

Rondas autolimpiables contra un calendario real a través del protocolo real. Un evento único: crear → intentar eliminar con un título incorrecto (debe rechazarse) → mover y renombrar → confirmar que aparece en el listado → eliminar → confirmar que ha desaparecido. Una serie de tres ocurrencias: editar un día, eliminar un día, eliminar la serie completa, comprobando cada vez que exactamente un día ha cambiado. Si una eliminación falla, el uid del evento sobrante se imprime en lugar de dejarse silenciosamente.

La ronda de asistentes solo se ejecuta cuando se pasa una dirección explícitamente, porque envía correos reales:

python tests/write_cycle.py "Calendar name" someone@example.com

tests/probe.jsonl es un conjunto de mensajes de protocolo sin procesar para comprobar el protocolo de enlace y la ruta de lectura:

python src/server.py < tests/probe.jsonl

Limitaciones conocidas

• Los eventos de día completo se pueden crear, pero no se puede mover su hora.

• Las reglas de recurrencia se crean en sus formas comunes (cada día / semana / mes / año, con un recuento o una fecha de fin). Las reglas más complejas ("cada segundo martes", conjuntos de días de la semana) se leen y expanden correctamente, pero no se pueden crear mediante la herramienta.

• Los recordatorios y alarmas no se gestionan.

• Los asistentes siempre se invitan como participantes obligatorios; no se exponen asistentes opcionales ni roles por asistente.

• Verificado solo con Yandex Calendar. Es probable que otros servidores CalDAV funcionen, pero no se han probado.

Licencia

MIT: consulte LICENSE.