Servidor MCP de TickTick -- La integración completa de TickTick para Claude

License: MIT Version Python Tools Glama

28 herramientas. CRUD completo. Consultas inteligentes. Filtros multicondición. Operaciones por lotes. Soporte para GTD. Compatible con Dida365.

Conecta Claude a tu cuenta de TickTick y gestiona todo tu sistema de tareas mediante una conversación natural: crea tareas, busca en proyectos, comprueba qué está vencido, crea elementos por lotes y mantente organizado sin abrir la aplicación.

"¿Qué está vencido?" --> Muestra al instante todos los plazos incumplidos en todos los proyectos.

¿Por qué este servidor?

Característica	Este servidor	TickTick MCP oficial	jacepark12
Herramientas	28	22	~20
Filtro multicondición	Sí (prioridad + etiqueta + fecha + proyecto)	Sí	No
Mover tarea entre proyectos	Sí	Sí	No
Completar en lote	Sí (hasta 20)	Sí (hasta 20)	No
Actualización por lotes	Sí	Sí	No
Vista de tareas completadas	Sí	Sí	No
Búsqueda entre proyectos	Búsqueda de texto completo	Sí	Sí
Subtareas	Sí	No	No
Vista de enfoque GTD	Sí (prioridad alta + vencimiento + vencido)	No	Parcial
Soporte para Dida365	Sí (URL base configurable)	No	Sí
Async (httpx)	Sí	N/A	No (solicitudes síncronas)
Validación Pydantic	Sí (entradas tipadas)	N/A	No
Anotaciones MCP	Sí (readOnly, sugerencias destructivas)	N/A	No
Autohospedado / código abierto	Sí	No (servicio alojado)	Sí
Privacidad	100% local, solo tus tokens	Pasa por servidores de TickTick	100% local

Related MCP server: mcp-server-asana

Inicio rápido

Requisitos previos

Cuenta de TickTick
Python 3.10+
Claude Code o Claude Desktop

Paso 1 -- Clonar e instalar

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Paso 2 -- Registrar una aplicación de desarrollador en TickTick

Ve a developer.ticktick.com
Haz clic en New App y rellena cualquier nombre
Establece la OAuth Redirect URL en: http://localhost:8080/callback
Copia tu Client ID y Client Secret

Paso 3 -- Autenticarse

TICKTICK_CLIENT_ID=your_id TICKTICK_CLIENT_SECRET=your_secret .venv/bin/python3 setup_auth.py

Esto abrirá tu navegador para autorizar la aplicación. Haz clic en Allow: los tokens se guardan en ~/.ticktick_mcp/tokens.json y se actualizan automáticamente.

Paso 4 -- Registrar con Claude Code

claude mcp add ticktick \
  -e TICKTICK_CLIENT_ID=your_id \
  -e TICKTICK_CLIENT_SECRET=your_secret \
  -- /path/to/ticktick-mcp/.venv/bin/python3 /path/to/ticktick-mcp/server.py

Para Claude Desktop

Añade esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "ticktick": {
      "type": "stdio",
      "command": "/path/to/ticktick-mcp/.venv/bin/python3",
      "args": ["/path/to/ticktick-mcp/server.py"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_id",
        "TICKTICK_CLIENT_SECRET": "your_secret"
      }
    }
  }
}

Paso 5 -- Añadir la habilidad de productividad (opcional)

mkdir -p ~/.claude/skills/ticktick
cp skills/ticktick/SKILL.md ~/.claude/skills/ticktick/

Soporte para Dida365

Para Dida365 (la versión china de TickTick), establece estas variables de entorno:

TICKTICK_BASE_URL=https://api.dida365.com/open/v1
TICKTICK_TOKEN_URL=https://dida365.com/oauth/token

Ejemplos de uso

Tú dices	Qué sucede
"Recuérdame llamar al dentista el viernes"	Tarea creada con fecha de vencimiento
"Añade 'revisar informe Q1' a Trabajo, prioridad alta"	Tarea en el proyecto Trabajo, prioridad 5
"¿Qué está vencido?"	Muestra todas las tareas vencidas en todos los proyectos
"¿En qué debería centrarme?"	Vista GTD: prioridad alta + vence hoy + vencido
"Busca cualquier cosa sobre 'presupuesto'"	Búsqueda de texto completo en todos los proyectos
"Muéstrame todas las tareas de prioridad alta"	Filtra por prioridad=5 en todos los proyectos
"¿Qué vence esta semana?"	Tareas que vencen en los próximos 7 días
"Crea tareas: comprar leche, llamar a Juan, enviar informe"	Crea 3 tareas por lotes
"Crea un proyecto llamado 'Planificación de vacaciones'"	Nuevo proyecto creado
"Añade la subtarea 'Comprar protector solar' bajo la tarea de vacaciones"	Subtarea creada
"Terminé la tarea del dentista"	Tarea marcada como completada
"Elimina el antiguo proyecto Sprint"	Proyecto y todas sus tareas eliminados

Referencia de herramientas MCP

Proyectos (5 herramientas)

Herramienta	Descripción
`ticktick_list_projects`	Lista todos los proyectos con IDs, nombres y colores
`ticktick_get_project`	Obtiene detalles de un proyecto específico
`ticktick_get_project_with_tasks`	Obtiene detalles del proyecto + todas las tareas pendientes en una llamada
`ticktick_create_project`	Crea un nuevo proyecto (nombre, color, modo de vista)
`ticktick_update_project`	Actualiza el nombre, color o modo de vista de un proyecto
`ticktick_delete_project`	Elimina permanentemente un proyecto

Tareas -- CRUD básico (7 herramientas)

Herramienta	Descripción
`ticktick_list_tasks`	Lista todas las tareas en un proyecto específico
`ticktick_create_task`	Crea una tarea (título, fecha de vencimiento, prioridad, proyecto, etiquetas)
`ticktick_get_task`	Obtiene detalles completos de una tarea específica
`ticktick_update_task`	Actualiza título, contenido, fechas o prioridad
`ticktick_complete_task`	Marca una tarea como completada
`ticktick_delete_task`	Elimina permanentemente una tarea
`ticktick_create_subtask`	Crea una subtarea bajo una tarea principal

Tareas -- Consultas inteligentes (7 herramientas)

Herramienta	Descripción
`ticktick_get_all_tasks`	Obtiene todas las tareas en todos los proyectos activos
`ticktick_search_tasks`	Búsqueda de texto completo en títulos, contenido y subtareas
`ticktick_get_tasks_by_priority`	Filtra por prioridad (Ninguna/Baja/Media/Alta)
`ticktick_get_tasks_due_today`	Tareas que vencen hoy en todos los proyectos
`ticktick_get_overdue_tasks`	Todas las tareas vencidas en todos los proyectos
`ticktick_get_tasks_due_this_week`	Tareas que vencen en los próximos 7 días
`ticktick_get_tasks_due_in_days`	Tareas que vencen exactamente en N días

Tareas -- Lotes y productividad (5 herramientas)

Herramienta	Descripción
`ticktick_batch_create_tasks`	Crea múltiples tareas a la vez
`ticktick_batch_update_tasks`	Actualiza múltiples tareas a la vez
`ticktick_complete_tasks_bulk`	Marca hasta 20 tareas como completadas a la vez
`ticktick_move_task`	Mueve una tarea de un proyecto a otro
`ticktick_get_focus_tasks`	Vista de enfoque GTD: prioridad alta + vence hoy + vencido

Tareas -- Filtros avanzados (2 herramientas)

Herramienta	Descripción
`ticktick_filter_tasks`	Filtro multicondición: prioridad + etiqueta + rango de fechas + proyecto + estado
`ticktick_get_completed_tasks`	Ver tareas completadas en un proyecto

Usuario (1 herramienta)

Herramienta	Descripción
`ticktick_get_user_preferences`	Obtiene la configuración del usuario (zona horaria, inicio de semana, etc.)

Arquitectura

server.py              # 20 MCP tools, async httpx, Pydantic validation
setup_auth.py          # One-time OAuth 2.0 setup (browser-based)
~/.ticktick_mcp/       # Token storage (auto-refreshed)
skills/ticktick/       # Claude skill for natural task language

Decisiones de diseño:

Asincronía en todas partes -- httpx.AsyncClient para llamadas a la API sin bloqueo
Modelos de entrada Pydantic -- Entradas con tipos seguros y validados con mensajes de error claros
Anotaciones MCP -- readOnlyHint, destructiveHint para un uso más seguro de las herramientas
Actualización automática de tokens -- Los tokens se actualizan de forma transparente con un búfer de 60 segundos

Solución de problemas

"Given client ID does not match" -- Verifica dos veces tu Client ID en developer.ticktick.com.

Puerto 8080 ya en uso -- lsof -ti:8080 | xargs kill -9 y luego vuelve a intentarlo.

Tokens expirados -- Vuelve a ejecutar setup_auth.py para obtener nuevos tokens.

Claude no ve las herramientas -- Ejecuta claude mcp list para verificar el registro.

Contribución

¡Las contribuciones son bienvenidas! Por favor, abre un issue primero para discutir lo que te gustaría cambiar.

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Make your changes to server.py
# Test: python3 -c "from server import mcp; print(len(mcp._tool_manager._tools), 'tools')"

Enlaces

Licencia

MIT (c) Salen-Project

ticktick-mcp