Servidor MCP de TickTick

Mejore su flujo de trabajo TickTick con este servidor MCP. Basado en la biblioteca ticktick-py , ofrece capacidades de filtrado significativamente mejoradas, lo que permite que los asistentes de IA y las aplicaciones compatibles con MCP (como Claude Desktop, VS Code Agent Mode o mcp-use ) interactúen con sus tareas con mayor precisión y eficacia.

✨ Características

Este servidor proporciona acceso integral a las funcionalidades de TickTick a través de herramientas MCP, categorizadas de la siguiente manera:

• Gestión de tareas: crear, actualizar (incluida la conversión al formato de fecha de TickTick), eliminar, completar y mover tareas.

• Gestión de subtareas: cree subtareas vinculando tareas existentes.

• Recuperación de tareas:

  • Obtener todas las tareas no completadas.

  • Obtenga tareas por ID o campos específicos.

  • Obtenga tareas completadas dentro de un rango de fechas.

  • Obtener tareas de un proyecto específico.

  • Filtrar tareas según varios criterios (prioridad, proyecto, etiquetas, etc.).

• Gestión de proyectos/etiquetas: recupera todos los proyectos, etiquetas y carpetas de proyectos.

• Herramientas útiles: convierte cadenas de fecha y hora al formato TickTick requerido.

Consulte las definiciones de herramientas en el directorio src/ticktick_mcp/tools/ para obtener especificaciones detalladas.

🚀 Primeros pasos

Este servidor utiliza la biblioteca no oficial para interactuar con la API TickTick.

Prerrequisitos

• Python >= 3.10

• Acceso a TickTick y credenciales de API (ver más abajo).

Configuración

1. Registrar una aplicación TickTick: Antes de usar el servidor, debe registrar una aplicación con TickTick para obtener las credenciales de la API. Siga estos pasos según la documentación de ticktick-py :

   • Vaya a la documentación de TickTick OpenAPI e inicie sesión con su cuenta de TickTick.

   • Haga clic en Manage Apps en la esquina superior derecha.

   • Registra una nueva aplicación haciendo clic en el botón +App Name . Indica un nombre para tu aplicación (p. ej., "Servidor MCP").

   • Una vez creada, edita los detalles de la aplicación. Anota el Client ID y Client Secret generados.

   • Para la OAuth Redirect URL , introduzca la URL a la que desea ser redirigido después de autorizar la aplicación. No es necesario que sea una URL activa.

     • http://localhost:8080/redirect o http://127.0.0.1:8080/ son opciones comunes para el desarrollo local.

     • Asegúrese de que esta URL exacta esté guardada en sus variables de entorno.

2. Variables de entorno: El servidor requiere las credenciales de la API de TickTick que acaba de obtener, además de sus datos de acceso. Por defecto, busca un archivo .env ubicado en ~/.config/ticktick-mcp/.env .

   • El servidor podría crear el directorio ~/.config/ticktick-mcp/ si no existe, pero es más seguro crearlo manualmente.

   • Debes crear el archivo dentro de ese directorio.

   • Como alternativa, puede especificar un directorio diferente usando el argumento de línea de comandos --dotenv-dirsolo al ejecutar el servidor directamente desde Python (consulte "Ejecución del servidor" más adelante). El archivo .env debe contener:

3. Autenticación (primera ejecución): en la primera ejecución (ya sea directamente o a través de un cliente MCP), la biblioteca ticktick-py subyacente iniciará un flujo de autenticación OAuth2.

   • Es posible que se abra automáticamente una ventana del navegador web o que se imprima una URL en la salida de la consola/registro.

   • Debe visitar esta URL, iniciar sesión en TickTick si es necesario y autorizar la aplicación (otorgar permisos de lectura y escritura).

   • Después de la autorización, será redirigido al TICKTICK_REDIRECT_URI que especificó.

     • La consola le pedirá que pegue esta URL redirigida completa (que incluye un parámetro code= ) nuevamente en la terminal.

   • Tras la verificación exitosa, se creará un archivo .token-oauth en el mismo directorio que su archivo .env .

   • Este archivo almacena en caché el token de autorización, por lo que normalmente solo necesitará realizar este paso de autorización manual una vez cada aproximadamente 6 meses o si el token deja de ser válido.

Ejecución del servidor

Puedes ejecutar el servidor de dos formas principales:

1. A través de un cliente MCP (recomendado para la integración del Asistente de IA):

Configure su cliente MCP (como Claude Desktop, VS Code Agent Mode, etc.) para usar el servidor. Ejemplo de configuración:

🔧 Herramientas

Este servidor proporciona las siguientes herramientas para interactuar con el servicio de gestión de tareas TickTick:

Gestión de tareas

1. ticktick_create_task

   • Crea una nueva tarea en TickTick

   • Entradas:

     • title (cadena): El título de la tarea. Obligatorio.

     • projectId (cadena, opcional): ID del proyecto al que agregar la tarea.

     • content (cadena, opcional): detalles o notas adicionales para la tarea.

     • desc (cadena, opcional): Descripción de la tarea.

     • allDay (booleano, opcional): Establezca en Verdadero si la tarea abarca todo el día.

     • startDate (cadena, opcional): fecha/hora de inicio en formato ISO 8601.

     • dueDate (cadena, opcional): fecha/hora de vencimiento en formato ISO 8601.

     • timeZone (cadena, opcional): nombre de la zona horaria de IANA (por ejemplo, 'Asia/Seúl').

     • reminders (matriz de cadenas, opcional): lista de activadores de recordatorios en formato RFC 5545.

     • repeat (cadena, opcional): regla recurrente en formato RFC 5545.

     • priority (entero, opcional): Prioridad de la tarea (0=Ninguna, 1=Baja, 3=Media, 5=Alta).

     • sortOrder (entero, opcional): valor de orden de clasificación personalizado.

     • items (matriz de objetos, opcional): Lista de diccionarios de subtareas.

2. ticktick_update_task

   • Actualiza una tarea existente

   • Entradas:

     • task_object (objeto): Un diccionario con propiedades de tarea para actualizar, incluido el id de la tarea.

3. ticktick_delete_tasks

   • Elimina una o más tareas

   • Entradas:

     • task_ids (cadena o matriz de cadenas): un único ID de tarea o una lista de ID de tareas para eliminar.

4. ticktick_complete_task

   • Marca una tarea como completada

   • Entradas:

     • task_id (cadena): El ID de la tarea que se marcará como completada.

5. ticktick_move_task

   • Mueve una tarea a un proyecto diferente

   • Entradas:

     • task_id (cadena): El ID de la tarea a mover.

     • new_project_id (cadena): El ID del proyecto de destino.

6. ticktick_make_subtask

   • Convierte una tarea en una subtarea de otra

   • Entradas:

     • parent_task_id (cadena): el ID de la tarea que se convertirá en la principal.

     • child_task_id (cadena): el ID de la tarea que se convertirá en la subtarea.

Recuperación de tareas

7. ticktick_get_by_id

   • Recupera un objeto específico (tarea, proyecto, etc.) por ID

   • Entradas:

     • obj_id (cadena): el ID único del objeto a recuperar.

8. ticktick_get_all

   • Recupera todos los objetos de un tipo especificado

   • Entradas:

     • search (cadena): el tipo de objetos a recuperar (por ejemplo, 'tareas', 'proyectos', 'etiquetas').

9. ticktick_get_tasks_from_project

   • Recupera todas las tareas no completadas de un proyecto específico

   • Entradas:

     • project_id (cadena): El ID del proyecto.

10. ticktick_filter_tasks

• Filtra tareas según varios criterios

• Entradas:

  • filter_criteria (objeto): Diccionario con parámetros de filtrado como:

    • status (cadena): estado de la tarea ('no completada' o 'completada').

    • project_id (cadena, opcional): ID del proyecto por el cual filtrar tareas.

    • tag_label (cadena, opcional): Nombre de la etiqueta por la que filtrar las tareas.

    • priority (entero, opcional): Nivel de prioridad.

    • due_start_date (cadena, opcional): fecha de inicio en formato ISO para el filtro de fecha de vencimiento.

    • due_end_date (cadena, opcional): fecha de finalización en formato ISO para el filtro de fecha de vencimiento.

    • completion_start_date (cadena, opcional): fecha de inicio para el filtro de fecha de finalización.

    • completion_end_date (cadena, opcional): Fecha de finalización para el filtro de fecha de finalización.

    • sort_by_priority (booleano, opcional): ordena los resultados por prioridad.

    • tz (cadena, opcional): zona horaria para la interpretación de la fecha.

Herramientas de ayuda

11. ticktick_convert_datetime_to_ticktick_format

• Convierte la cadena de fecha y hora ISO 8601 al formato API de TickTick

• Entradas:

  • datetime_iso_string (cadena): La cadena de fecha/hora en formato ISO 8601.

  • tz (cadena): nombre de la zona horaria de IANA para interpretar la fecha/hora.

🤖 Ejemplo de mensaje de agente

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en abrir un problema o enviar una solicitud de incorporación de cambios.

📜 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

🔗 Ver también

• Servidores de protocolo de contexto de modelo : el repositorio central para implementaciones de referencia de servidores MCP para diversas herramientas y plataformas.

• modelcontextprotocol.io : Documentación oficial del Protocolo de Contexto de Modelo.

• pietrozullo/mcp-use : una biblioteca de Python popular para crear clientes/agentes que interactúan con servidores MCP.

• lazeroffmichael/ticktick-py : la biblioteca de API de TickTick no oficial utilizada por este proyecto para manejar la autenticación y las interacciones de API.