TickTick

Gestiona tareas, proyectos y hábitos usando la API de TickTick.

Documentación

Servidor MCP de TickTick

Servidor MCP para la API de TickTick, que permite la gestión de tareas, organización de proyectos, seguimiento de hábitos y más.

Características

✅ Gestión de Tareas: Crear, leer, actualizar y eliminar tareas con todas las propiedades disponibles
📊 Gestión de Proyectos: Crear, leer, actualizar y eliminar proyectos con vistas personalizables
📋 Soporte de Subtareas: Soporte completo para gestionar subtareas dentro de tareas principales
🔄 Control Completo de Tareas: Establecer prioridades, fechas de vencimiento, recordatorios y reglas recurrentes
🔐 Autenticación OAuth: Implementación completa de OAuth2 para acceso seguro a la API
⚠️ Manejo Integral de Errores: Mensajes de error claros para problemas comunes

Herramientas

get_task_by_ids
- Obtener una tarea específica por ID de proyecto e ID de tarea
- Entradas:
  - projectId (cadena): Identificador del proyecto
  - taskId (cadena): Identificador de la tarea
- Devuelve: Objeto de tarea que coincide con TickTickTaskSchema
create_task
- Crear una nueva tarea en un proyecto
- Entradas:
  - title (cadena): Título de la tarea
  - projectId (cadena): ID del proyecto
  - content (cadena opcional): Contenido de la tarea
  - desc (cadena opcional): Descripción de la tarea
  - isAllDay (booleano opcional): Es tarea de todo el día
  - startDate (cadena opcional): Fecha de inicio de la tarea en formato "yyyy-MM-dd'T'HH:mm:ssZ"
  - dueDate (cadena opcional): Fecha de vencimiento de la tarea en formato "yyyy-MM-dd'T'HH:mm:ssZ"
  - timeZone (cadena opcional): Zona horaria de la tarea (por ejemplo, "America/Los_Angeles")
  - reminders (cadena[] opcional): Lista de disparadores de recordatorio en formato iCalendar
  - repeatFlag (cadena opcional): Indicador de repetición de la tarea en formato iCalendar
  - priority (número opcional): Prioridad de la tarea (Ninguna: 0, Baja: 1, Media: 3, Alta: 5)
  - sortOrder (cadena opcional): Orden de clasificación de la tarea
  - items (matriz opcional): Lista de subtareas con:
    - title (cadena): Título del elemento de subtarea
    - startDate (cadena opcional): Fecha de la subtarea en formato "yyyy-MM-dd'T'HH:mm:ssZ"
    - isAllDay (booleano opcional): Es elemento de subtarea de todo el día
    - sortOrder (número opcional): Orden de clasificación del elemento de subtarea
    - timeZone (cadena opcional): Zona horaria de la subtarea
    - status (número opcional): Estado de finalización (Normal: 0, Completado: 1)
    - completedTime (cadena opcional): Hora de finalización en formato "yyyy-MM-dd'T'HH:mm:ssZ"
- Devuelve: Objeto de tarea creado que coincide con TickTickTaskSchema
update_task
- Actualizar una tarea existente
- Entradas:
  - taskId (cadena): Identificador de la tarea - Ruta
  - id (cadena): Identificador de la tarea - Cuerpo
  - projectId (cadena): ID del proyecto
  - Todos los campos opcionales de create_task
- Devuelve: Objeto de tarea actualizado que coincide con TickTickTaskSchema
complete_task
- Marcar una tarea como completada
- Entradas:
  - taskId (cadena): Identificador de la tarea
  - projectId (cadena): Identificador del proyecto
- Devuelve: vacío
delete_task
- Eliminar una tarea de un proyecto
- Entradas:
  - taskId (cadena): Identificador de la tarea
  - projectId (cadena): Identificador del proyecto
- Devuelve: vacío
get_user_projects
- Obtener todos los proyectos del usuario autenticado
- Entradas: Ninguna
- Devuelve: Matriz de objetos de proyecto que coinciden con TickTickProjectSchema
get_project_by_id
- Obtener un proyecto específico por ID
- Entradas:
  - projectId (cadena): Identificador del proyecto
- Devuelve: Objeto de proyecto que coincide con TickTickProjectSchema
get_project_with_data
- Obtener detalles del proyecto junto con tareas y columnas
- Entradas:
  - projectId (cadena): Identificador del proyecto
- Devuelve: Objeto que contiene:
  - project: Objeto de proyecto que coincide con TickTickProjectSchema
  - tasks: Matriz de objetos de tarea que coinciden con TickTickTaskSchema
  - columns: Matriz opcional de objetos de columna con:
    - id (cadena opcional)
    - projectId (cadena opcional)
    - name (cadena opcional)
    - sortOrder (número opcional)
create_project
- Crear un nuevo proyecto
- Entradas:
  - name (cadena): Nombre del proyecto
  - color (cadena opcional): Color del proyecto (predeterminado: '#4772FA')
  - viewMode (cadena opcional): Modo de vista ('list', 'kanban', 'timeline') (predeterminado: 'list')
  - kind (cadena opcional): Tipo de proyecto ('TASK', 'NOTE') (predeterminado: 'TASK')
- Devuelve: Objeto de proyecto creado que coincide con TickTickProjectSchema
update_project
- Actualizar un proyecto existente
- Entradas:
  - projectId (cadena): Identificador del proyecto
  - name (cadena opcional): Nombre del proyecto
  - color (cadena opcional): Color del proyecto
  - sortOrder (número opcional): Orden de clasificación del proyecto
  - viewMode (cadena opcional): Modo de vista ('list', 'kanban', 'timeline')
  - kind (cadena opcional): Tipo de proyecto ('TASK', 'NOTE')
- Devuelve: Objeto de proyecto actualizado que coincide con TickTickProjectSchema
delete_project
- Eliminar un proyecto
- Entradas:
  - projectId (cadena): Identificador del proyecto
- Devuelve: vacío

Referencias de Esquemas

TickTickTaskSchema: Define la estructura de los objetos de tarea, incluyendo:
- Propiedades básicas de la tarea (id, título, descripción)
- Configuración de fechas y horas
- Prioridad y estado
- Elementos de lista de verificación y subtareas
TickTickProjectSchema: Define la estructura de los objetos de proyecto, incluyendo:
- Identificación y nombre del proyecto
- Configuración de visualización (color, modo de vista)
- Permisos y organización

Propiedades de Tareas

Al crear o actualizar tareas, puedes incluir estas propiedades:

Niveles de Prioridad:
- 0: Ninguna
- 1: Baja
- 3: Media
- 5: Alta
Valores de Estado:
- 0: Normal (no completada)
- 2: Completada
Formato de Recordatorio:
- Ejemplo: ["TRIGGER:P0DT9H0M0S", "TRIGGER:PT0S"]
- Sigue el formato TRIGGER de iCalendar
Reglas Recurrentes (repeatFlag):
- Ejemplo: "RRULE:FREQ=DAILY;INTERVAL=1"
- Utiliza reglas de recurrencia RFC 5545
Formato de Fecha:
- Formato ISO 8601: "yyyy-MM-dd'T'HH:mm:ssZ"
- Ejemplo: "2019-11-13T03:00:00+0000"

Propiedades de Proyectos

Al crear o actualizar proyectos, puedes usar estas propiedades:

Modos de Vista:
- "list": Vista de lista estándar
- "kanban": Vista de tablero Kanban
- "timeline": Vista de línea de tiempo
Tipos de Proyecto:
- "TASK": Proyecto orientado a tareas
- "NOTE": Proyecto orientado a notas

Configuración

Autenticación OAuth

Para habilitar la autenticación OAuth con TickTick, deberás registrar tu aplicación y obtener credenciales de API:

Crea una cuenta en el Portal de Desarrolladores de TickTick
Registra una nueva aplicación
Establece la URL de redirección de OAuth a: http://localhost:8000/callback
Copia el ID de Cliente generado (TICKTICK_CLIENT_ID) y el Secreto de Cliente (TICKTICK_CLIENT_SECRET)

Flujo de Autorización por Primera Vez

Al usar el servidor MCP de TickTick por primera vez:

Se te pedirá autorizar la aplicación
Se abrirá una ventana del navegador con la página de inicio de sesión de TickTick
Después de iniciar sesión, se te pedirá otorgar permisos
El token de acceso se mostrará en la página
Copia este token y establécelo como variable de entorno TICKTICK_ACCESS_TOKEN

Generar Token de Acceso

Cuando necesites generar un nuevo token de acceso (ya sea para la configuración inicial o cuando el token expire), sigue estos pasos:

Configura tus credenciales usando uno de estos métodos:

Opción 1: Archivo .env (Recomendado)

Crea un archivo .env en la raíz de tu proyecto:
```
TICKTICK_CLIENT_ID="<YOUR_CLIENT_ID>"
TICKTICK_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
```
Luego cárgalo:
```
source .env
```
Este método es recomendado porque:
- Las credenciales persisten entre sesiones de terminal
- Es más fácil gestionar múltiples configuraciones
- Menos propenso a fugas en el historial del shell
- Se puede respaldar fácilmente (recuerda excluirlo del control de versiones)
Opción 2: Variables de Entorno del Terminal

Usa comillas simples si tus credenciales contienen caracteres especiales. Ten en cuenta que estas variables solo persistirán en tu sesión de terminal actual:
```
export TICKTICK_CLIENT_ID='<YOUR_CLIENT_ID>'
export TICKTICK_CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
```
Ejecuta el comando de autenticación:

Si usas el paquete publicado:
```
npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth
```
Si ejecutas el servidor MCP localmente:
```
npm run start:auth
```
El proceso:
- Lanzará tu navegador predeterminado
- Te dirigirá a la página de inicio de sesión de TickTick
- Solicitará los permisos necesarios
- Generará y mostrará tu token de acceso

Guarda el token de acceso:

echo "TICKTICK_ACCESS_TOKEN=\"<GENERATED_TOKEN>\"" >> .env
source .env

Consejos de Seguridad:

Agrega .env a tu archivo .gitignore

Nunca comprometas credenciales en el control de versiones

Los tokens de acceso expiran después de 180 días: deberás regenerarlos

Uso con Claude Desktop

Para usar esto con Claude Desktop, agrega lo siguiente a tu claude_desktop_config.json:

NPX

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@alexarevalo.ai/mcp-server-ticktick"],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "ticktick": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TICKTICK_CLIENT_ID",
        "-e",
        "TICKTICK_CLIENT_SECRET",
        "-e",
        "TICKTICK_ACCESS_TOKEN",
        "mcp/ticktick"
      ],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Instalación vía Smithery

Para instalar ticktick-mcp-server para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @alexarevalo9/ticktick-mcp-server --client claude

Compilación

Compilación de Docker:

docker build -t mcp/ticktick -f src/ticktick/Dockerfile .

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.