Servidor MCP de Donetick

Un servidor de Protocolo de Contexto de Modelo (MCP) para la gestión de tareas domésticas de Donetick. Permite a Claude y otros asistentes de IA compatibles con MCP interactuar con tu instancia de Donetick a través de una API con límite de velocidad.

Características

• 16 Herramientas MCP: Gestión completa de tareas (listar, obtener, crear, completar, actualizar, eliminar, saltar), organización de etiquetas (listar, crear, actualizar, eliminar), información de miembros del círculo, gestión de usuarios (listar usuarios del círculo, obtener perfil de usuario)

• Integración completa de API: Utiliza la API Completa de Donetick (/api/v1/) con todos los endpoints configurados correctamente con barras inclinadas finales

• Soporte total de campos: Los 26+ campos de creación de tareas funcionan, incluidos metadatos de frecuencia, programaciones rotativas, múltiples asignados, estrategias de asignación, notificaciones, etiquetas, prioridad, puntos, subtareas y más

• Uso consistente de mayúsculas en campos: Campos en camelCase en todo momento (name, description, dueDate, createdBy, etc.)

• Herramientas de actualización especializadas: Actualiza detalles de tareas, prioridad y asignado con endpoints dedicados

• Autenticación JWT: Gestión automática de tokens con renovación transparente

• Caché inteligente: Caché inteligente para operaciones get_chore (TTL de 60 s por defecto)

• Límite de velocidad: Algoritmo de cubeta de tokens evita la sobrecarga de la API

• Lógica de reintento: Retroceso exponencial con fluctuación para operaciones resilientes

• Async/Await: Operaciones no bloqueantes usando httpx

• Validación de entrada: Validadores de campo de Pydantic con saneamiento

• Seguridad reforzada: Obligación de HTTPS, registro sanitizado, mensajes de error seguros, seguridad de token JWT

• Soporte Docker: Despliegue en contenedor con mejores prácticas de seguridad

• Pruebas exhaustivas: Pruebas unitarias/de integración simuladas + marco de pruebas de API en vivo con pytest

• Seguridad de tipos: Modelos Pydantic para validación de solicitudes/respuestas

Inicio rápido

Instalación más sencilla (CLI de Claude Code):

claude mcp add donetick uvx donetick-mcp-server@latest

Luego configura tus credenciales de Donetick cuando se te solicite.

O instala manualmente con uvx:

# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Beneficios:

• ✅ No requiere instalación: se ejecuta directamente desde PyPI

• ✅ Actualizaciones automáticas con el indicador --refresh

• ✅ Entorno aislado: sin conflictos

• ✅ Funciona en Windows, macOS, Linux

Requisitos

• Instancia de Donetick (autoalojada o en la nube)

• Credenciales de cuenta de Donetick (nombre de usuario y contraseña)

• Para el método uvx: uv instalado (ver Inicio rápido)

• Para otros métodos: Python 3.11 o superior

Instalación

Opción 1: uvx (Recomendado - Sin necesidad de instalación)

Ver Inicio rápido más arriba.

El indicador --refresh garantiza que siempre obtengas la última versión cuando Claude Desktop se reinicie.

Opción 2: Docker

1. Clonar el repositorio:

   git clone https://github.com/jason1365/donetick-mcp-server.git
   cd donetick-mcp-server

2. Crear archivo .env:

   cp .env.example .env
   # Edit .env with your configuration

3. Configurar variables de entorno:

   DONETICK_BASE_URL=https://your-instance.com
   DONETICK_USERNAME=your_username
   DONETICK_PASSWORD=your_password
   LOG_LEVEL=INFO

4. Construir y ejecutar:

   docker-compose build
   docker-compose up -d

Opción 3: pip install (Para integración con el sistema)

Si deseas instalarlo globalmente o en un entorno virtual:

# Install from PyPI
pip install donetick-mcp-server

# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .

# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.server

Luego configura Claude Desktop para usar el comando instalado:

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Autenticación

El servidor MCP utiliza autenticación basada en JWT con tus credenciales de Donetick.

Lo que necesitas:

• Tu nombre de usuario de Donetick (el mismo que el inicio de sesión web)

• Tu contraseña de Donetick (la misma que el inicio de sesión web)

Cómo funciona:

1. El servidor inicia sesión con tus credenciales al arrancar

2. El token JWT se recibe y almacena en memoria

3. El token se renueva automáticamente antes de que expire

4. No se requiere gestión manual de tokens

Seguridad:

• Las credenciales se almacenan solo en variables de entorno o en el archivo .env

• Los tokens JWT se mantienen solo en memoria (nunca se persisten en disco)

• La renovación automática de tokens evita la expiración de la sesión

• Se requiere HTTPS para todas las conexiones

Integración con Claude Desktop

Método más sencillo - CLI de Claude Code:

claude mcp add donetick uvx donetick-mcp-server@latest

O edita manualmente el archivo de configuración:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Configuración uvx (Recomendada)

{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Nota: El indicador --refresh actualiza automáticamente a la última versión.

Configuración Docker

{
  "mcpServers": {
    "donetick": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "donetick-mcp-server",
        "python",
        "-m",
        "donetick_mcp.server"
      ]
    }
  }
}

Configuración pip install

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Después de actualizar la configuración, reinicia Claude Desktop.

Herramientas disponibles

1. list_chores

Lista todas las tareas con filtrado opcional.

Parámetros:

• filter_active (booleano, opcional): Filtrar por estado activo

• assigned_to_user_id (entero, opcional): Filtrar por ID de usuario asignado

Ejemplo:

List all active chores assigned to me

2. get_chore

Obtiene los detalles de una tarea específica por ID.

Parámetros:

• chore_id (entero, obligatorio): El ID de la tarea

Ejemplo:

Show me details of chore 123

3. create_chore

Crea una nueva tarea con soporte de configuración completa.

Parámetros básicos:

• name (cadena, obligatorio): Nombre de la tarea (1-200 caracteres)

• description (cadena, opcional): Descripción de la tarea (máx. 5000 caracteres)

• due_date (cadena, opcional): Fecha de vencimiento en formato YYYY-MM-DD o RFC3339

• created_by (entero, opcional): ID de usuario creador

Parámetros de recurrencia/frecuencia:

• frequency_type (cadena, opcional): Con qué frecuencia se repite la tarea - "once", "daily", "weekly", "monthly", "yearly", "interval_based" (por defecto: "once")

• frequency (entero, opcional): Multiplicador de frecuencia, ej., 1=semanal, 2=quincenal (por defecto: 1)

• frequency_metadata (objeto, opcional): Configuración adicional de frecuencia como {"days": [1,3,5], "time": "09:00"}

• is_rolling (booleano, opcional): Programación rotativa (próximo vencimiento basado en finalización) vs fija (por defecto: false)

Parámetros de asignación de usuario:

• assigned_to (entero, opcional): ID de usuario asignado principal

• assignees (arreglo, opcional): Múltiples asignados como [{"userId": 1}, {"userId": 2}]

• assign_strategy (cadena, opcional): Estrategia de asignación - "least_completed", "round_robin", "random" (por defecto: "least_completed")

Parámetros de notificación:

• notification (booleano, opcional): Habilitar notificaciones (por defecto: false)

• nagging (booleano, opcional): Habilitar notificaciones de recordatorio (por defecto: false)

• predue (booleano, opcional): Habilitar notificaciones previas a la fecha de vencimiento (por defecto: false)

Parámetros de organización:

• priority (entero, opcional): Nivel de prioridad 1-5 (1=más baja, 5=más alta)

• labels (arreglo, opcional): Etiquetas como ["cleaning", "outdoor"]

Parámetros de estado:

• is_active (booleano, opcional): Estado activo - las tareas inactivas están ocultas (por defecto: true)

• is_private (booleano, opcional): Tarea privada visible solo para el creador (por defecto: false)

Parámetros de gamificación:

• points (entero, opcional): Puntos otorgados por completar

Parámetros avanzados:

• sub_tasks (arreglo, opcional): Subtareas/elementos de lista de verificación

Ejemplos:

Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10

Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1

Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 points

4. complete_chore

Marca una tarea como completada.

Parámetros:

• chore_id (entero, obligatorio): El ID de la tarea

• completed_by (entero, opcional): ID de usuario que la completó

Ejemplo:

Mark chore 123 as complete

5. delete_chore

Elimina una tarea permanentemente. Solo el creador puede eliminar.

Parámetros:

• chore_id (entero, obligatorio): El ID de la tarea

Ejemplo:

Delete chore 123

6. get_circle_members

Obtiene todos los miembros de tu círculo (hogar/equipo). Muestra a quién puedes asignar tareas.

Parámetros: Ninguno

Devuelve:

• ID de usuario

• Nombre de usuario

• Nombre para mostrar

• Rol (admin/member)

• Estado activo

• Puntos y puntos canjeados

Ejemplo:

Show me who's in my household
Who can I assign chores to?
List all circle members

Configuración

Variables de entorno

Límite de velocidad

El servidor implementa un limitador de velocidad de cubeta de tokens para evitar la sobrecarga de la API:

• Por defecto: 10 solicitudes por segundo con capacidad de ráfaga de 10

• Conservador: Comienza de forma conservadora y se puede aumentar según tu instancia de Donetick

• Respeta 429: Se retira automáticamente cuando la API limita la velocidad

Lógica de reintento

• Retroceso exponencial con fluctuación para fallos transitorios

• Máximo 3 reintentos para la mayoría de las operaciones

• Reintento inteligente: Solo reintenta en errores 5xx y 429 (límite de velocidad)

• Sin reintento en 4xx: Los errores de cliente fallan inmediatamente (excepto 429)

Desarrollo

Ejecución de pruebas

Pruebas simuladas (rápidas, no requieren instancia de Donetick):

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (unit + integration with mocks)
pytest

# Run with coverage
pytest --cov=donetick_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py
pytest tests/test_server.py

# Run with verbose output
pytest -v

Pruebas de API en vivo (requieren instancia de Donetick):

# Create .env file with credentials (see Configuration section)
# Then run live API integration tests
pytest tests/integration/test_live_api.py -v

# Skip live tests
pytest -m "not live_api"

# Run only live tests
pytest -m live_api

Detalles de cobertura de pruebas:

• Pruebas simuladas validan lógica, comportamiento de reintento, límite de velocidad, manejo de errores

• Pruebas de API en vivo verifican enrutamiento de endpoints, compatibilidad de mayúsculas en campos, formatos de respuesta

• Cobertura completa garantiza tanto la fiabilidad del cliente API como la corrección de las herramientas MCP

Estructura del proyecto

donetick-mcp-server/
├── src/donetick_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── client.py           # Donetick API client
│   ├── models.py           # Pydantic data models
│   └── config.py           # Configuration management
├── tests/
│   ├── test_client.py      # API client tests
│   └── test_server.py      # MCP server tests
├── tmp/                    # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

Nota: El directorio tmp/ se utiliza para scripts de prueba temporales y archivos de análisis durante el desarrollo. Está en gitignore y no se incluye en las versiones.

Documentación de la API

Este servidor utiliza la API Completa de Donetick (/api/v1/) con autenticación JWT.

Recursos oficiales

• Documentación de Donetick: https://docs.donetick.com/

• GitHub de Donetick: https://github.com/donetick/donetick

Arquitectura de la API

Endpoints utilizados:

• Listar tareas: GET /api/v1/chores/ (requiere barra inclinada final)

• Obtener tarea: GET /api/v1/chores/{id} (incluye subtareas)

• Crear tarea: POST /api/v1/chores/

• Actualizar tarea: PUT /api/v1/chores/{id} (nombre, descripción, nextDueDate)

• Actualizar prioridad: PUT /api/v1/chores/{id}/priority

• Actualizar asignado: PUT /api/v1/chores/{id}/assignee

• Saltar tarea: PUT /api/v1/chores/{id}/skip

• Completar tarea: POST /api/v1/chores/{id}/do

• Eliminar tarea: DELETE /api/v1/chores/{id}

• Obtener miembros: GET /api/v1/circles/members/ (requiere barra inclinada final)

Importante: Los endpoints de lista requieren barras inclinadas finales (/api/v1/chores/, /api/v1/circles/members/). El cliente lo maneja automáticamente.

Notas importantes

1. Se usa la API Completa: No la API externa (eAPI) - utiliza la API Completa interna

2. Mayúsculas en campos: camelCase consistente en todo momento (name, description, dueDate, createdBy)

3. Barras inclinadas finales: Los endpoints de lista incluyen barras inclinadas finales para un enrutamiento adecuado

4. Autenticación: Tokens JWT Bearer con gestión automática

5. Soporte completo de funciones: Los 26+ campos de creación de tareas disponibles

6. Renovación automática de tokens: Los tokens JWT se renuevan de forma transparente

7. Ámbito del círculo: Todas las operaciones se limitan a tu círculo (hogar/equipo)

8. Sin restricciones premium: Todas las funciones disponibles a través de la API completa

Solución de problemas

Problemas comunes

"La variable de entorno DONETICK_BASE_URL es obligatoria"

• Asegúrate de que tu archivo .env existe y tiene el formato correcto

• Para Docker: asegúrate de que las variables de entorno se pasen en docker-compose.yml

"Límite de velocidad alcanzado, esperando..."

• El servidor está respetando los límites de velocidad de la API

• Considera reducir RATE_LIMIT_PER_SECOND si esto ocurre con frecuencia

"Conexión rechazada" o errores de tiempo de espera

• Verifica que la URL de tu instancia de Donetick sea correcta

• Comprueba que tu instancia de Donetick sea accesible

• Asegúrate de que las reglas del cortafuegos permitan conexiones salientes

"401 No autorizado" o "Credenciales inválidas"

• Verifique que su nombre de usuario y contraseña sean correctos

• Compruebe que su cuenta no esté bloqueada o deshabilitada

• Asegúrese de poder iniciar sesión en la interfaz web de Donetick con las mismas credenciales

• Revise si hay errores tipográficos en las variables de entorno

Herramientas que no se muestran en Claude

• Reinicie Claude Desktop después de los cambios de configuración

• Revise los registros de Claude Desktop en busca de errores

• Verifique que la ruta del archivo de configuración sea correcta

Depuración

Habilite el registro de depuración:

export LOG_LEVEL=DEBUG

O en Docker:

environment:
  - LOG_LEVEL=DEBUG

Ver registros de Docker:

docker-compose logs -f donetick-mcp

Seguridad

• Credenciales: Nunca confíe credenciales al control de versiones (use el archivo .env)

• Tokens JWT: Almacenados solo en memoria, nunca persistidos en disco

• Actualización automática de tokens: Evita la expiración de la sesión sin intervención del usuario

• Aislamiento de Docker: Se ejecuta como usuario no root en el contenedor

• Límites de recursos: Los límites de memoria y CPU evitan el agotamiento de recursos

• Validación de entrada: Los modelos Pydantic validan todas las entradas

• HTTPS requerido: El servidor exige HTTPS para todas las conexiones de Donetick

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Haga un fork del repositorio

2. Cree una rama de funcionalidad

3. Agregue pruebas para la nueva funcionalidad

4. Asegúrese de que todas las pruebas pasen

5. Envíe una solicitud de extracción

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles

Agradecimientos

• Donetick - Gestión de tareas de código abierto

• Model Context Protocol - Especificación MCP

• Anthropic - SDK MCP y Claude

Soporte

• Problemas: https://github.com/jason1365/donetick-mcp-server/issues

• Documentación de Donetick: https://docs.donetick.com

• Documentación de MCP: https://modelcontextprotocol.io

Construido con ❤️ para las comunidades de Donetick y MCP