TaskChampion MCP

Servidor MCP para la gestión de tareas de Taskwarrior 3.x, TaskChampion y Timewarrior con 35 herramientas para el ciclo de vida completo de tareas, validación de esquemas, permisos basados en roles y seguimiento de tiempo.

GitHub

Documentación

TaskChampion MCP

Un servidor de Model Context Protocol para Taskwarrior 3.x, TaskChampion y Timewarrior.

Para los veteranos de Unix con barba y los vaqueros del teclado que gestionan su vida desde la terminal — y ahora quieren que su LLM eche una mano. 🧔⌨️

Última versión: v1.0.4 — pip install taskchampion-mcp / uvx taskchampion-mcp

¿Qué es esto?

TaskChampion MCP es un servidor de Model Context Protocol que permite a los LLM leer, crear, modificar y gestionar tus tareas de Taskwarrior y tus entradas de tiempo de Timewarrior. Envuelve las herramientas CLI de task y timew y las expone como herramientas MCP estructuradas que cualquier asistente de IA compatible puede invocar.

¿Por qué? El autor aloja TaskChampion en un servidor doméstico y quería una forma limpia de que los LLM colaboraran en la planificación de proyectos, la descomposición de tareas y el seguimiento del tiempo — sin ceder el control de la base de datos de tareas.

Plataformas compatibles

Plataforma	Transporte	Estado
Neovim (vía Claude Code CLI)	stdio	v1.0.4
Cursor	stdio	v1.0.4
Windsurf	stdio	v1.0.4
VS Code (Copilot MCP)	stdio	v1.0.4
Claude Desktop	stdio	v1.0.4
Transportes HTTP/SSE	HTTP/SSE	Diferido a v1.x

Requisitos:

Python 3.10+
Taskwarrior 3.x (sincronización TaskChampion)
Timewarrior (opcional, para funciones de seguimiento de tiempo)

Instalación rápida

# With uv (recommended)
uv tool install taskchampion-mcp

# With pip
pip install taskchampion-mcp

Luego configura los ajustes MCP de tu IDE para usar:

{
  "mcpServers": {
    "taskchampion": {
      "command": "taskchampion-mcp-server",
      "args": []
    }
  }
}

Guías de instalación por destino: Claude Desktop | Windsurf | Cursor | Neovim

Primera ejecución

En una instalación nueva sin config.toml, el servidor arranca en modo de incorporación. Todas las herramientas son visibles en tools/list, pero las herramientas operativas devuelven errores estructurados de schema_unset hasta que se completa la incorporación (ADR 19). Terminas la incorporación persistiendo dos claves en ~/.config/taskchampion-mcp/config.toml:

role — lo que el LLM puede hacer (CONTRIBUTOR / GENERATOR / MANAGER)
schema o schema_path — qué esquema de tareas valida el servidor

Tres formas de llegar:

Deja que el LLM te guíe. Conecta tu IDE al servidor MCP sin configuración y pregunta: "Ayúdame a configurar TaskChampion MCP." El LLM llama primero a get_runtime_capabilities, ve mode: "onboarding", y luego usa get_initialization_status -> propose_initialization_options -> use_preset_schema (o save_initial_schema). El servidor se recarga automáticamente al tener éxito — no se necesita reiniciar.
Ejecuta el asistente CLI: ./dev.sh init (interactivo) o ./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive (con guion).
Edita config.toml a mano — consulta quick_start.md. Dos claves, y luego llama a reload_configuration desde el LLM (o reinicia el IDE).

Los tres caminos son intercambiables y producen el mismo estado. Elige según quién deba escribir — consulta initialization_flows.md para la guía de decisión.

Niveles de permiso

Controla lo que el LLM puede hacer con tus tareas mediante tres roles acumulativos:

Rol	Puede leer	Puede anotar/modificar	Puede crear	Puede completar/eliminar
CONTRIBUTOR	✅	✅	❌	❌
GENERATOR	✅	✅	✅	❌
MANAGER	✅	✅	✅	✅

Establece el rol en ~/.config/taskchampion-mcp/config.toml:

[server]
role = "GENERATOR"  # CONTRIBUTOR | GENERATOR | MANAGER

Esquemas de tareas

Taskwarrior admite flujos de trabajo personalizados mediante UDA (atributos definidos por el usuario). TaskChampion MCP incluye ajustes preestablecidos de esquemas que enseñan al LLM la estructura de tus tareas:

Esquema	Descripción
`minimal`	Solo campos integrados (prioridad, proyecto, etiquetas)
`gtd`	Getting Things Done (contextos, energía, próximas acciones)
`scrum`	Basado en sprints (puntos de historia, IDs de sprint, criterios de aceptación)
`kanban`	Columnas de tablero, límites WIP, clases de servicio
`authors_custom_example`	Ejemplo avanzado del mundo real con fases de ciclo de vida, investigación basada en hipótesis y seguimiento de procedencia del LLM

En la primera ejecución, el MCP te pedirá seleccionar un esquema o generar uno automáticamente a partir de tus tareas existentes.

Seguridad

Esta herramienta da a un LLM acceso indirecto a tu CLI de gestión de tareas. La seguridad no es opcional:

Sin ejecución de shell — todas las llamadas CLI usan listas de argumentos de subprocess, nunca shell=True
Saneamiento de entrada — todas las entradas del LLM se validan contra listas permitidas antes de pasarlas a la CLI
Límite de velocidad — topes configurables por minuto/hora evitan bucles descontrolados
Registro de auditoría — cada operación se registra con marca de tiempo, herramienta, parámetros, resultado y result_code
Sobres etiquetados con código — cada respuesta de herramienta incluye un campo estable code para ramificaciones seguras para máquinas
Modo de simulación — cada operación destructiva admite vista previa dry_run sin mutación
Modo de confirmación — las operaciones de ciclo de vida usan tokens de confirmación explícitos cuando la confirmación está habilitada
Redacción de campos sensibles — campos configurables ocultos de las respuestas del LLM

Consulta ADR 9, ADR 13 y ADR 14 para el diseño completo de seguridad y observabilidad.

Compatibilidad con Taskwarrior

Versión	Estado
Taskwarrior 3.x (TaskChampion)	✅ Totalmente compatible
Taskwarrior 2.x (Taskserver/taskd)	⏳ Planificado para una versión futura

Nos centramos en la pila moderna Taskwarrior 3.x + TaskChampion. Taskserver (taskd) está obsoleto y recibirá soporte limitado en una versión futura. Consulta ADR 8.

Documentación

Carpeta / archivo	Contenido
`docs/adrs/`	Registros de decisiones de arquitectura
`docs/references/`	Referencia de herramientas upstream (Taskd, TaskChampion, Timewarrior)
`docs/manuals/quick_start.md`	Configuración manual de `config.toml`
`docs/manuals/configuration_reference.md`	Referencia completa de claves de configuración con reglas de precedencia
`docs/manuals/schema_authoring.md`	Cómo escribir esquemas de tareas personalizados
`docs/manuals/security_model.md`	Controles de seguridad para usuarios finales
`docs/manuals/initialization_flows.md`	Qué ruta de inicialización usar (impulsada por LLM vs CLI vs edición manual)
`docs/manuals/targets/`	Guías de instalación por IDE (Claude Desktop, Windsurf, Cursor, Neovim)
`docs/manuals/logrotate.md`	Rotación de registros de auditoría
`docs/llm_context/`	Directrices para agentes LLM y supuestos registrados
`docs/CONTRIBUTING.md`	Cómo contribuir (ramas, PRs, versionado)
`docs/ROADMAP.md`	Hoja de ruta de funciones (v0.1.0 → v1.0.0)
`docs/releases/v1.0.4.md`	Notas de la versión v1.0.2 y enlaces de instalación
`docs/manuals/release_checklist.md`	Lista de verificación previa a la publicación de etiquetas
`src/taskchampion_mcp/schemas/`	Ajustes preestablecidos de esquemas de tareas incluidos (TOML)
`scripts/setup_remote.sh`	Arranque de un solo paso en host remoto

Solución de problemas

Problemas comunes de primera ejecución y configuración. Guías detalladas en docs/manuals/quick_start.md y docs/manuals/initialization_flows.md.

Síntoma	Causa probable	Solución
Las herramientas devuelven errores `schema_unset` después de conectar	A `~/.config/taskchampion-mcp/config.toml` le falta `role` o `schema`/`schema_path`	Añade ambos bajo `[server]` y llama a `reload_configuration` (o reinicia).
La instalación de Linux Claude Desktop se completa pero taskchampion nunca aparece	Error de ruta en minúsculas anterior a v0.3.0 en dev.sh	Actualiza a v0.3.0+. Linux: `C` en mayúsculas en `~/.config/Claude/`.
`set_role("MANAGER")` devuelve `role_elevation_forbidden`	La auto-elevación vía MCP está prohibida (ADR 17)	Edita `config.toml` a mano, luego llama a `reload_configuration`.
El servidor MCP falla al iniciar con `Taskwarrior not found on PATH`	`task` no está instalado o no está en el `PATH` del servidor MCP	Instala Taskwarrior 3.x. Establece `task_binary` en la configuración si es necesario.
Cowork / Claude Desktop: el JSON de instalación se sobrescribe al salir	Se escribió la configuración mientras Claude Desktop estaba en ejecución	Cierra Claude Desktop primero, o usa `./dev.sh reinstall claude -r`.
La superficie de herramientas no incluye herramientas de incorporación ni de contribuidor	El servidor no pudo iniciar (revisa stderr)	Ejecuta `taskchampion-mcp-server` desde un shell para ver el error.

Para modos de fallo más profundos, cada herramienta MCP devuelve un campo estable error_code (ADR 14) y cada llamada se registra en auditoría (ADR 13) en ~/.local/share/taskchampion-mcp/audit.log por defecto.

Contribuir

Consulta docs/CONTRIBUTING.md para la guía completa. Puntos clave:

Crea ramas desde dev, PR a qa, publica desde qa a main
Versionado semántico (vMAJOR.MINOR.PATCH)
Las contribuciones asistidas por LLM deben atribuirse (consulta docs/llm_context/AGENTS.md)
Todos los supuestos no verificados deben registrarse en docs/llm_context/assumptions_and_ideas.md

Licencia

Apache License 2.0 — uso libre para fines privados y comerciales. Se requiere atribución mediante el archivo NOTICE.

Este proyecto se inició con la asistencia de Claude claude-sonnet-4-20250514 vía Windsurf Cascade.