TaskChampion MCP

Servidor MCP para gerenciamento de tarefas com Taskwarrior 3.x, TaskChampion e Timewarrior, com 35 ferramentas para ciclo de vida completo de tarefas, validação de esquema, permissões baseadas em funções e controle de tempo.

GitHub

Documentação

TaskChampion MCP

Um servidor Model Context Protocol para Taskwarrior 3.x, TaskChampion e Timewarrior.

Para os aficionados por Unix e cowboys de teclado que gerenciam suas vidas pelo terminal — e agora querem que seu LLM dê uma ajuda. 🧔⌨️

Última versão: v1.0.4 — pip install taskchampion-mcp / uvx taskchampion-mcp

O Que É Isso?

TaskChampion MCP é um servidor Model Context Protocol que permite que LLMs leiam, criem, modifiquem e gerenciem suas tarefas do Taskwarrior e entradas de tempo do Timewarrior. Ele encapsula as ferramentas CLI task e timew e as expõe como ferramentas MCP estruturadas que qualquer assistente de IA compatível pode chamar.

Por quê? O autor hospeda TaskChampion em um servidor doméstico e queria uma forma limpa de permitir que LLMs cooperassem no planejamento de projetos, decomposição de tarefas e controle de tempo — sem abrir mão do controle do banco de dados de tarefas.

Plataformas Suportadas

Plataforma	Transporte	Status
Neovim (via 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	Adiado para v1.x

Requisitos:

Python 3.10+
Taskwarrior 3.x (sincronização TaskChampion)
Timewarrior (opcional, para recursos de controle de tempo)

Instalação Rápida

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

# With pip
pip install taskchampion-mcp

Em seguida, configure as configurações de MCP do seu IDE para usar:

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

Guias de instalação por destino: Claude Desktop | Windsurf | Cursor | Neovim

Primeira Execução

Em uma instalação nova sem config.toml, o servidor inicia no modo de integração. Todas as ferramentas ficam visíveis em tools/list, mas as ferramentas operacionais retornam erros estruturados de schema_unset até que a integração seja concluída (ADR 19). Você finaliza a integração persistindo duas chaves em ~/.config/taskchampion-mcp/config.toml:

role — o que o LLM pode fazer (CONTRIBUTOR / GENERATOR / MANAGER)
schema ou schema_path — qual esquema de tarefas o servidor valida

Três maneiras de chegar lá:

Deixe o LLM guiá-lo pelo processo. Conecte seu IDE ao servidor MCP sem configuração e pergunte: "Ajude-me a configurar o TaskChampion MCP." O LLM chama get_runtime_capabilities primeiro, vê mode: "onboarding", e então usa get_initialization_status -> propose_initialization_options -> use_preset_schema (ou save_initial_schema). O servidor recarrega automaticamente em caso de sucesso — sem necessidade de reiniciar.
Execute o assistente CLI: ./dev.sh init (interativo) ou ./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive (scriptado).
Edite config.toml manualmente — veja quick_start.md. Duas chaves, depois chame reload_configuration pelo LLM (ou reinicie o IDE).

Os três caminhos são intercambiáveis e produzem o mesmo estado. Escolha com base em quem deve digitar — veja initialization_flows.md para o guia de decisão.

Níveis de Permissão

Controle o que o LLM pode fazer com suas tarefas por meio de três funções cumulativas:

Função	Pode Ler	Pode Anotar/Modificar	Pode Criar	Pode Concluir/Excluir
CONTRIBUTOR	✅	✅	❌	❌
GENERATOR	✅	✅	✅	❌
MANAGER	✅	✅	✅	✅

Defina a função em ~/.config/taskchampion-mcp/config.toml:

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

Esquemas de Tarefas

O Taskwarrior suporta fluxos de trabalho personalizados via UDAs (User Defined Attributes). O TaskChampion MCP inclui predefinições de esquema que ensinam ao LLM sua estrutura de tarefas:

Esquema	Descrição
`minimal`	Apenas campos integrados (prioridade, projeto, tags)
`gtd`	Getting Things Done (contextos, energia, próximas ações)
`scrum`	Baseado em sprints (story points, IDs de sprint, critérios de aceitação)
`kanban`	Colunas de quadro, limites de WIP, classes de serviço
`authors_custom_example`	Exemplo avançado do mundo real com fases de ciclo de vida, pesquisa orientada por hipóteses e rastreamento de proveniência de LLM

Na primeira execução, o MCP solicitará que você selecione um esquema ou gere um automaticamente a partir de suas tarefas existentes.

Segurança

Esta ferramenta dá a um LLM acesso indireto à sua CLI de gerenciamento de tarefas. Segurança não é opcional:

Sem execução de shell — todas as chamadas CLI usam listas de argumentos de subprocesso, nunca shell=True
Sanitização de entrada — todas as entradas do LLM validadas contra listas de permissão antes de passar para a CLI
Limitação de taxa — limites configuráveis por minuto/hora evitam loops descontrolados
Registro de auditoria — cada operação registrada com timestamp, ferramenta, parâmetros, resultado e result_code
Envelopes com tags de código — cada resposta de ferramenta inclui um campo estável code para ramificação segura para máquinas
Modo de simulação — toda operação destrutiva suporta pré-visualização dry_run sem mutação
Modo de confirmação — operações de ciclo de vida usam tokens de confirmação explícitos quando a confirmação está habilitada
Redação de campos sensíveis — campos configuráveis ocultos das respostas do LLM

Veja ADR 9, ADR 13 e ADR 14 para o design completo de segurança e observabilidade.

Compatibilidade com Taskwarrior

Versão	Status
Taskwarrior 3.x (TaskChampion)	✅ Totalmente suportado
Taskwarrior 2.x (Taskserver/taskd)	⏳ Planejado para versão futura

Focamos na stack moderna Taskwarrior 3.x + TaskChampion. O Taskserver (taskd) está obsoleto e receberá suporte limitado em uma versão futura. Veja ADR 8.

Documentação

Pasta / arquivo	Conteúdo
`docs/adrs/`	Registros de Decisão de Arquitetura
`docs/references/`	Referência de ferramentas upstream (Taskd, TaskChampion, Timewarrior)
`docs/manuals/quick_start.md`	Configuração manual de `config.toml`
`docs/manuals/configuration_reference.md`	Referência completa de chaves de configuração com regras de precedência
`docs/manuals/schema_authoring.md`	Escrevendo esquemas de tarefas personalizados
`docs/manuals/security_model.md`	Controles de segurança para usuários finais
`docs/manuals/initialization_flows.md`	Qual caminho de inicialização usar (orientado por LLM vs CLI vs edição manual)
`docs/manuals/targets/`	Guias de instalação por IDE (Claude Desktop, Windsurf, Cursor, Neovim)
`docs/manuals/logrotate.md`	Rotação de logs de auditoria
`docs/llm_context/`	Diretrizes de agentes LLM e premissas rastreadas
`docs/CONTRIBUTING.md`	Como contribuir (ramificações, PRs, versionamento)
`docs/ROADMAP.md`	Roadmap de recursos (v0.1.0 → v1.0.0)
`docs/releases/v1.0.4.md`	Notas da versão v1.0.2 e links de instalação
`docs/manuals/release_checklist.md`	Checklist de publicação pré-tag
`src/taskchampion_mcp/schemas/`	Predefinições de esquema de tarefas incluídas (TOML)
`scripts/setup_remote.sh`	Bootstrap de host remoto em uma única execução

Solução de Problemas

Problemas comuns de primeira execução e configuração. Guias detalhados estão em docs/manuals/quick_start.md e docs/manuals/initialization_flows.md.

Sintoma	Causa provável	Correção
Ferramentas retornam erros `schema_unset` após conectar	`~/.config/taskchampion-mcp/config.toml` está sem `role` ou `schema`/`schema_path`	Adicione ambos em `[server]` e chame `reload_configuration` (ou reinicie).
Instalação no Claude Desktop Linux conclui, mas taskchampion nunca aparece	Bug de caminho minúsculo pré-v0.3.0 no dev.sh	Atualize para v0.3.0+. Linux: `C` maiúsculo em `~/.config/Claude/`.
`set_role("MANAGER")` retorna `role_elevation_forbidden`	Auto-elevação via MCP é proibida (ADR 17)	Edite manualmente `config.toml`, depois chame `reload_configuration`.
Servidor MCP falha na inicialização com `Taskwarrior not found on PATH`	`task` não instalado ou não está no `PATH` do servidor MCP	Instale Taskwarrior 3.x. Defina `task_binary` na configuração se necessário.
Cowork / Claude Desktop: JSON de instalação sobrescrito ao sair	Config gravada enquanto o Claude Desktop estava em execução	Saia do Claude Desktop primeiro, ou use `./dev.sh reinstall claude -r`.
Superfície de ferramentas não inclui ferramentas de integração nem de contribuidor	Servidor falhou ao iniciar (verifique stderr)	Execute `taskchampion-mcp-server` a partir de um shell para ver o erro.

Para modos de falha mais profundos, toda ferramenta MCP retorna um campo estável error_code (ADR 14) e toda chamada é registrada em auditoria (ADR 13) em ~/.local/share/taskchampion-mcp/audit.log por padrão.

Contribuindo

Veja docs/CONTRIBUTING.md para o guia completo. Pontos-chave:

Ramifique a partir de dev, PR para qa, lance de qa para main
Versionamento semântico (vMAJOR.MINOR.PATCH)
Contribuições assistidas por LLM devem ser atribuídas (veja docs/llm_context/AGENTS.md)
Todas as premissas não verificadas devem ser registradas em docs/llm_context/assumptions_and_ideas.md

Licença

Apache License 2.0 — use livremente para fins privados e comerciais. Atribuição exigida via arquivo NOTICE.

Este projeto foi iniciado com assistência do Claude claude-sonnet-4-20250514 via Windsurf Cascade.