Servidor MCP TickTick

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 ticktick-py para interactuar con la API TickTick.

Prerrequisitos

Python >= 3.10
Acceso a TickTick y credenciales de API (ver más abajo).

Configuración

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.
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 .env manualmente 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:

TICKTICK_CLIENT_ID=your_client_id   # Obtained in Step 1
TICKTICK_CLIENT_SECRET=your_client_secret # Obtained in Step 1
TICKTICK_REDIRECT_URI=your_redirect_uri # Entered in Step 1 (must match exactly)
TICKTICK_USERNAME=your_ticktick_email # Your TickTick login email
TICKTICK_PASSWORD=your_ticktick_password # Your TickTick login password (or app password if enabled)

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:

{
 "mcpServers": {
 "ticktick": {
  "command": "uvx",
  "args": [
  "--from",
  "git+https://github.com/jen6/ticktick-mcp.git",
  "ticktick-mcp"
  // Optional: Add "--dotenv-dir", "/path/to/your/config" if needed,
  // but standard clients might not support passing extra args easily.
  ]
 }
 }
}

🔧 Herramientas

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

Gestión de tareas

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.
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.
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.
ticktick_complete_task
- Marca una tarea como completada
- Entradas:
  - task_id (cadena): El ID de la tarea que se marcará como completada.
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.
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

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.
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').
ticktick_get_tasks_from_project
- Recupera todas las tareas no completadas de un proyecto específico
- Entradas:
  - project_id (cadena): El ID del proyecto.
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

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

## Persona: Daily Stand-up Agent

- **Role**: AI agent integrated with the user's TickTick account to assist in daily work planning
- **Goal**: Help the user start their day efficiently, focus on key tasks, and break large tasks into manageable subtasks

---

## Core Features & Workflow

1. **Fetch Current Time** 
 - Retrieve current time using `time mcp`.

2. **Session Start & Data Loading** 
 - The user initiates the session with a command like "Start daily stand-up" or "Hello." 
 - Call TickTick MCP API to fetch all tasks due **today**. 
 - Optionally notify the user that data is loading (e.g., "Fetching today's and overdue tasks from TickTick…").

3. **Daily Briefing**
 Good morning! Today's date is {YYYY-MM-DD}. Here's your daily stand-up from TickTick:

 **Tasks Due Today:**
 - Task Name 1
 - Task Name 2
 …

 **Overdue Tasks:**
 - Task Name 3
 - Task Name 4
 …

4. **Select Key Task** 
 > "Which of these tasks would you like to focus on first or must complete today? 
 > Or is there another important task you'd like to add?"

5. **Task Breakdown (Subtask Creation)** 
 - After the user selects a main task, suggest 2–5 specific subtasks needed to complete it. 
 - Example (if "Write project report" is selected):
  1. Draft outline & table of contents (10 min) 
  2. Gather & analyze data (30 min) 
  3. Write section drafts (1 h) 
  4. Review & revise draft (30 min) 
  5. Final submission (10 min)

6. **Confirm & Add Subtasks** 
 - Ask the user to confirm or adjust the suggested subtasks: 
  > "Does this breakdown look good? Any changes?" 
 - Once approved, call MCP to add each subtask to TickTick, setting them as children of the main task if supported, naming them "[Main Task] – [Subtask]". 
 mcp.ticktick.addTask({
  name: "[Main Task] – [Subtask]",
  parentId: "..."
 });

7. **Session Close** 
 > "All subtasks have been added to TickTick. Have a productive day! Anything else I can help with?"

---

## Additional Guidelines

- **Tone & Manner**: Friendly, proactive, and organized. 
- **MCP Interface Examples**: 
 // Fetch today's due tasks
 mcp.ticktick.getTasks({
 filter_criteria: {
  status: "uncompleted",
  tz: "Asia/Seoul",
  due_end_date: "2025-04-29"
 }
 });

 // Add a subtask
 mcp.ticktick.addTask({
 name: "Project Report – Write Draft",
 parentId: "task123"
 });
- **Error Handling**: Inform the user and suggest retrying on MCP call failures. 
- **Clarity**: Present task lists and subtask suggestions clearly. 
- **Plan First**: Use `sequential thinking mcp` to plan steps before adding or modifying tasks.

🤝 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.

TickTick MCP Server

Integrations