Todoist

Servidor MCP do Todoist

Um servidor MCP (Model Context Protocol) que conecta o Claude ao Todoist para gerenciamento completo de tarefas e projetos por meio de linguagem natural.

Instalação

Claude Desktop (Instalação com um clique)

1. Baixe todoist-mcp.mcpb da versão mais recente
2. Clique duas vezes no arquivo (ou arraste para o Claude Desktop)
3. Insira seu token da API do Todoist quando solicitado
4. Comece a conversar: "Mostre-me meus projetos do Todoist"

Claude Code / Outros clientes MCP

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Recursos

• 19 ferramentas MCP para gerenciamento completo do Todoist
• Gerenciamento de tarefas: Crie, atualize, exclua, conclua e reabra tarefas com prioridades, datas de vencimento e rótulos
• Operações em lote: Processe várias tarefas com eficiência
• Subtarefas: Gerenciamento hierárquico de tarefas com acompanhamento de conclusão
• Projetos e seções: Suporte completo de organização
• Rótulos, filtros e lembretes: Recursos Pro/Business suportados
• Linguagem natural: Adição rápida com o processamento de linguagem natural do Todoist
• Modo de simulação (dry-run): Teste operações sem fazer alterações

Modo de simulação (dry-run)

O modo de simulação permite testar operações e automações sem fazer alterações reais no seu espaço de trabalho do Todoist. É perfeito para testar, depurar, aprender a API ou validar scripts de automação antes de executá-los de verdade.

Como ativar o modo de simulação

Adicione DRYRUN=true à sua configuração de ambiente:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

O que o modo de simulação faz

• Valida operações: Usa dados reais da API para validar se as operações seriam bem-sucedidas
• Simula mutações: Operações de criação, atualização, exclusão e conclusão são simuladas (não executadas)
• Consultas com dados reais: Operações de leitura (obter tarefas, projetos, rótulos) usam a API real
• Registro detalhado: Mostra exatamente o que aconteceria com prefixos claros de [DRY-RUN]
• Detecção de erros: Captura os mesmos erros que ocorreriam na execução real

Casos de uso

• Teste de automações: Valide operações complexas em lote antes de executar
• Aprendizado da API: Explore a funcionalidade sem medo de fazer alterações indesejadas
• Depuração de problemas: Entenda quais operações seriam executadas
• Experimentação segura: Experimente novos fluxos de trabalho sem afetar suas tarefas reais
• Treinamento e demonstrações: Mostre como as operações funcionam sem modificar dados reais

Exemplo de uso

Com o modo de simulação ativado, as operações mostram o que aconteceria:

You: "Create a task called 'Test Task' in my Work project"

Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none

Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)

Operações suportadas

Todas as 19 ferramentas MCP suportam o modo de simulação:

• Criação, atualização, conclusão e exclusão de tarefas
• Operações de subtarefas e alterações de hierarquia
• Operações em lote em várias tarefas
• Criação de projetos e seções
• Operações de gerenciamento de rótulos
• Operações CRUD de lembretes
• Criação de comentários

Desativando o modo de simulação

Remova a variável de ambiente DRYRUN ou defina-a como false e reinicie o Claude Desktop para voltar ao modo de operação normal.

Visão geral das ferramentas

O servidor fornece 19 ferramentas MCP para gerenciamento completo do Todoist:

Para documentação detalhada das ferramentas com parâmetros e exemplos, consulte TOOLS_REFERENCE.md.

Solução de problemas

Problemas comuns

"Nenhum projeto do Todoist encontrado" ou erros de conexão:

• Verifique se o token da sua API está correto
• Verifique se o token está configurado corretamente no seu claude_desktop_config.json
• Certifique-se de que não há espaços extras ou aspas ao redor do seu token

Servidor MCP não carrega:

• Confirme se o pacote está instalado globalmente: npm list -g @greirson/mcp-todoist
• Reinicie o Claude Desktop completamente
• Verifique se o caminho do arquivo de configuração está correto para o seu sistema operacional
• Tente o caminho completo para o binário mcp-todoist: /Users/USERNAME/.npm-global/bin/mcp-todoist

Erros de permissão:

• No macOS/Linux, talvez seja necessário criar o diretório de configuração: mkdir -p ~/.config
• Certifique-se de que o Claude Desktop tenha permissão para ler o arquivo de configuração

Exemplos de uso

Configuração de projetos e seções

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

Criação e gerenciamento de tarefas

"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"

# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"

Adição rápida

A ferramenta de adição rápida processa texto em linguagem natural como o aplicativo Todoist, suportando vários recursos em um único comando:

"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"

Sintaxe da adição rápida:

• Datas de vencimento: Datas em linguagem natural como "amanhã", "próxima sexta-feira", "23 de jan", "em 3 dias"
• Projetos: #ProjectName (sem espaços nos nomes dos projetos)
• Rótulos: @label (por exemplo, "@urgent", "@work")
• Responsáveis: +name (para projetos compartilhados)
• Prioridade: p1 (urgente), p2, p3, p4 (mais baixa)
• Prazos: {in 3 days} ou {March 15}
• Descrições: //your description here (devem estar no final)

Gerenciamento de subtarefas

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

Operações em lote

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

Gerenciamento de comentários

"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"

Gerenciamento de rótulos

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

Gerenciamento de lembretes (Pro/Business)

"Show me all my reminders"
"Get reminders for task 'Team Meeting'"
"Create a reminder for task 'Review PR' 30 minutes before due"
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
"Update reminder 67890 to trigger at 10:00 instead"
"Delete reminder 67890"

Descoberta de tarefas

"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"

Testes e validação

"Test my Todoist connection"
"Run basic tests on all Todoist features" // Default: read-only API tests
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
"Benchmark Todoist API performance with 10 iterations"
"Validate that all MCP tools are working correctly"

Testes no modo de simulação

Quando o modo de simulação está ativado (DRYRUN=true), use comandos normais — eles serão simulados automaticamente:

"Create a test task with priority 1"
"Update all overdue tasks to be due tomorrow"
"Delete all completed tasks in project 12345"
"Create 5 subtasks under task 'Project Planning'"

Todas essas operações serão validadas com seus dados reais, mas não farão alterações.

Desenvolvimento

Compilando a partir do código-fonte

# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git

# Navigate to directory
cd mcp-todoist

# Install dependencies
npm install

# Build the project
npm run build

Comandos de desenvolvimento

# Watch for changes and rebuild
npm run watch

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Arquitetura

O código segue uma arquitetura limpa e modular, projetada para manutenibilidade e escalabilidade:

Estrutura principal

• src/index.ts: Ponto de entrada principal do servidor com roteamento de solicitações
• src/types.ts: Definições de tipos e interfaces TypeScript
• src/type-guards.ts: Funções de validação de tipos em tempo de execução
• src/validation.ts: Validação e sanitização de entrada
• src/errors.ts: Tipos de erro personalizados com tratamento estruturado
• src/cache.ts: Cache em memória para otimização de desempenho

Organização modular de ferramentas

• src/tools/: Definições de ferramentas MCP específicas de domínio, organizadas por funcionalidade:
  • task-tools.ts — Gerenciamento de tarefas (9 ferramentas)
  • subtask-tools.ts — Operações de subtarefas (5 ferramentas)
  • project-tools.ts — Gerenciamento de projetos/seções (4 ferramentas)
  • comment-tools.ts — Operações de comentários (2 ferramentas)
  • label-tools.ts — Gerenciamento de rótulos (5 ferramentas)
  • reminder-tools.ts — Operações de lembretes (4 ferramentas)
  • test-tools.ts — Testes e validação (3 ferramentas)
  • index.ts — Exportações centralizadas

Manipuladores de lógica de negócios

• src/handlers/: Módulos de lógica de negócios separados por domínio:
  • task-handlers.ts — CRUD de tarefas e operações em lote
  • subtask-handlers.ts — Gerenciamento hierárquico de tarefas
  • project-handlers.ts — Operações de projetos e seções
  • comment-handlers.ts — Criação e recuperação de comentários
  • label-handlers.ts — CRUD de rótulos e estatísticas
  • reminder-handlers.ts — CRUD de lembretes via API Sync
  • test-handlers.ts — Infraestrutura de testes de API
  • test-handlers-enhanced/ — Estrutura abrangente de testes CRUD

Módulos utilitários

• src/utils/: Funções utilitárias compartilhadas:
  • api-helpers.ts — Utilitários de tratamento de respostas da API
  • error-handling.ts — Gerenciamento centralizado de erros
  • parameter-transformer.ts — Conversão de formato de parâmetros de MCP para SDK do Todoist
  • dry-run-wrapper.ts — Implementação do modo de simulação

Registro de alterações

Consulte CHANGELOG.md para obter um histórico detalhado de todas as alterações.

Para guias de migração e alterações significativas, consulte o registro de alterações completo.

Contribuindo

Contribuições são bem-vindas! Este projeto é mantido ativamente e agradeço o interesse da comunidade em melhorá-lo.

Uma nota sobre contribuições assistidas por IA

Eu uso o Claude Code como parte do meu próprio fluxo de trabalho de desenvolvimento — a codificação assistida por IA é uma parte normal de como este projeto é construído. Incentivo os contribuidores a usar as ferramentas que os tornarem produtivos, incluindo assistentes de codificação por IA.

Dito isso, as ferramentas de IA facilitam muito a geração de grandes volumes de código que parecem corretos, mas introduzem problemas sutis: mapeamentos incorretos de API, regressões de desempenho, alterações de tipos que quebram a compatibilidade ou aumento de escopo que agrupa recursos não relacionados. Já vi PRs que trocam um prefixo de URL sem perceber que os próprios caminhos da API mudaram, ou que adicionam paginação buscando todas as páginas todas as vezes sem preservar o parâmetro limit.

Por causa disso, todo PR recebe uma revisão arquitetural completa. Não se trata de controle de acesso — trata-se de manter um código do qual centenas de pessoas dependem por meio de seus clientes MCP. PRs que parecem ser saída de IA não revisada receberão feedback detalhado sobre o que precisa mudar e por quê, para que você possa aprender e reenviar.

Requisitos para PRs

Antes de enviar um pull request, certifique-se de:

1. Uma preocupação por PR. Uma correção de bug é um PR. Um novo recurso é outro. Uma atualização de documentação é outro. Se o seu diff tocar em mais de 40 arquivos em recursos não relacionados, ele precisa ser dividido. PRs com escopo misto serão devolvidos para divisão.

2. Você entende o que seu código faz. Se uma ferramenta de IA o escreveu, leia-o criticamente antes de enviar. Você consegue explicar por que cada alteração é necessária? Conseguiria depurá-lo se quebrasse? Se não, não está pronto.

3. Testes são incluídos ou atualizados. Novos recursos precisam de testes. Correções de bugs precisam de um teste que teria capturado o bug. Se você está alterando endpoints de API, verifique se eles funcionam contra a API ao vivo — não confie apenas que uma troca de URL é suficiente.

4. Verificação manual é feita. Execute npm run build e npm test localmente. Se você está alterando código de integração de API, teste contra sua própria conta Todoist (o modo de execução seca está disponível com DRYRUN=true). Inclua evidências da verificação na descrição do seu PR.

5. CI deve passar. PRs com verificações de CI falhando não serão revisados até que estejam verdes.

O Que Torna um Bom PR

• Um título e corpo claros e descritivos explicando o quê e por quê
• Um diff focado e fácil de revisar (menos de 200 linhas alteradas é o ideal)
• Testes que demonstram que a alteração funciona
• Documentação atualizada se a alteração afeta o comportamento voltado ao usuário
• Sem alterações de formatação não relacionadas, refatorações ou melhorias "já que estou aqui"

Começando

1. Faça um fork do repositório
2. Crie um branch de recurso a partir de main
3. Faça suas alterações seguindo as diretrizes acima
4. Execute npm run build && npm test && npm run lint para verificar
5. Envie seu PR com uma descrição clara

Se você não tiver certeza se uma alteração é desejada ou como abordá-la, abra uma issue primeiro para discutir. Isso economiza tempo de todos e ajuda a alinhar a abordagem correta antes que o código seja escrito.

Licença

Este projeto é licenciado sob a Licença MIT — consulte o arquivo LICENSE para detalhes.

Issues e Suporte

Se você encontrar algum problema ou precisar de suporte, por favor, abra uma issue no repositório do GitHub.