Todoist MCP

oficial

Gerencie suas tarefas e projetos do Todoist diretamente do seu LLM.

GitHub
541
Experimente este MCPPatrocinado

O que você pode fazer com Todoist MCP?

  • Encontrar tarefas por data — Peça ao seu assistente para localizar tarefas agendadas para um dia específico usando findTasksByDate.
  • Adicionar novas tarefas — Peça ao seu assistente para criar uma ou mais tarefas no Todoist para você por meio da ferramenta addTasks.
  • Verificar identidade da conta — Pergunte qual conta do Todoist está conectada antes de fazer alterações, usando user-info para confirmar o usuário ativo.
  • Executar ferramentas diretamente — Use npm run tool para executar qualquer ferramenta de forma autônoma com argumentos JSON, ignorando o servidor MCP.

Documentação

Servidor Todoist MCP

Biblioteca para conectar agentes de IA ao Todoist. Inclui ferramentas que podem ser integradas a LLMs, permitindo que acessem e modifiquem uma conta Todoist em nome do usuário.

Essas ferramentas podem ser usadas tanto por meio de um servidor MCP, quanto importadas diretamente em outros projetos para integrá-las às suas próprias interfaces conversacionais de IA.

Usando as ferramentas

1. Adicione este repositório como dependência

npm install @doist/todoist-mcp

2. Importe as ferramentas e conecte-as a uma IA

Aqui está um exemplo usando o Vercel's AI SDK.

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/todoist-sdk'
import { streamText } from 'ai'

// Create Todoist API client
const client = new TodoistApi(process.env.TODOIST_API_KEY)

// Helper to wrap tools with the client
function wrapTool(tool, todoistClient) {
    return {
        ...tool,
        execute(args) {
            return tool.execute(args, todoistClient)
        },
    }
}

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Todoist assistant',
    tools: {
        findTasksByDate: wrapTool(findTasksByDate, client),
        addTasks: wrapTool(addTasks, client),
    },
})

Usando como servidor MCP

Início Rápido

Você pode executar o servidor MCP diretamente com npx:

npx @doist/todoist-mcp

Guia de Configuração

O servidor Todoist MCP está disponível como um serviço HTTP streamable para fácil integração com diversos clientes de IA:

URL Principal (HTTP Streamable): https://ai.todoist.net/mcp

Claude Desktop

  1. Abra Configurações → Conectores → Adicionar conector personalizado
  2. Insira https://ai.todoist.net/mcp e conclua a autenticação OAuth

Cursor

Crie um arquivo de configuração:

  • Global: ~/.cursor/mcp.json
  • Específico do projeto: .cursor/mcp.json
{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

Em seguida, ative o servidor nas configurações do Cursor, se solicitado.

Claude Code (CLI)

A configuração mais rápida é o plugin oficial do Todoist, que configura o servidor MCP para você:

/plugin marketplace add doist/todoist-mcp
/plugin install todoist@doist

O OAuth é executado no seu navegador na primeira vez que você usa uma ferramenta do Todoist. Consulte a documentação do plugin da Anthropic para mais informações.

Se preferir configurar o servidor MCP manualmente, execute:

claude mcp add --transport http todoist https://ai.todoist.net/mcp

Em seguida, inicie o claude, execute /mcp e selecione o servidor MCP todoist para autenticar.

Visual Studio Code

  1. Abra a Paleta de Comandos → MCP: Adicionar Servidor
  2. Selecione o transporte HTTP e use:
{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

Outros Clientes MCP

npx -y mcp-remote https://ai.todoist.net/mcp

Para mais detalhes sobre como configurar e usar o servidor MCP, incluindo a criação de servidores personalizados, consulte docs/mcp-server.md.

Recursos

Uma característica fundamental deste projeto é que as ferramentas podem ser reutilizadas e não são escritas especificamente para uso em um servidor MCP. Elas podem ser conectadas como ferramentas a outras interfaces conversacionais de IA (por exemplo, o Vercel's AI SDK).

Este projeto está em seus estágios iniciais. Espere mais e/ou melhores ferramentas em breve.

No entanto, nosso objetivo é fornecer um pequeno conjunto de ferramentas que permitam fluxos de trabalho completos, em vez de apenas ações atômicas, encontrando um equilíbrio entre flexibilidade e eficiência para LLMs.

Para nossa filosofia de design, diretrizes e padrões de desenvolvimento, consulte docs/tool-design.md.

Ferramentas Disponíveis

Para uma lista completa das ferramentas disponíveis, consulte o diretório src/tools.

Compatibilidade com OpenAI MCP

Este servidor inclui as ferramentas search e fetch que seguem a especificação OpenAI MCP, permitindo integração perfeita com o protocolo MCP da OpenAI. Essas ferramentas retornam resultados codificados em JSON, otimizados para os requisitos da OpenAI, mantendo a compatibilidade com o ecossistema MCP mais amplo.

Dependências

Configuração do Servidor MCP

Consulte docs/mcp-server.md para instruções completas sobre como configurar o servidor MCP.

Configuração de Desenvolvimento Local

Consulte docs/dev-setup.md para instruções completas de configuração e CONTRIBUTING.md para fluxos de trabalho de contribuição e verificações de qualidade.

MCP Apps

Este projeto inclui suporte para MCP Apps – widgets de interface interativos renderizados inline em interfaces de chat de IA. Os widgets fornecem representações visuais ricas das saídas das ferramentas (por exemplo, listas de tarefas) em vez de texto simples.

Consulte docs/mcp-apps.md para a arquitetura dos widgets, pipeline de build e fluxo de trabalho de desenvolvimento.

Início Rápido

Após clonar e configurar o repositório:

  • npm start - Compilar e executar o inspetor MCP para testes
  • npm run dev - Modo de desenvolvimento com recompilação e reinicialização automáticas
  • npm run tool:list - Listar ferramentas disponíveis para execução direta
  • npm run tool -- <tool-name> '<json-args>' - Executar uma ferramenta diretamente sem MCP

Ao usar npm run tool, inclua -- antes dos argumentos da ferramenta para que o npm os encaminhe para scripts/run-tool.ts.

Exemplo de verificação antes de operações de escrita: npm run tool -- user-info '{}' Isso confirma a qual conta Todoist o TODOIST_API_KEY atual está conectado.

run-tool usa TODOIST_API_KEY do seu arquivo .env (criado a partir de .env.example por npm run setup). Use uma conta de teste ou um projeto temporário ao executar operações de escrita para evitar modificar dados reais.

Contribuindo

Consulte CONTRIBUTING.md para:

  • Fluxo de trabalho de desenvolvimento
  • Executar ferramentas diretamente com scripts/run-tool.ts
  • Testes e verificações de qualidade
  • Convenções de commit

Lançamento

Este projeto usa o release-please para automatizar o gerenciamento de versões e a publicação de pacotes.

Como funciona

  1. Faça suas alterações usando Conventional Commits:

    • feat: para novos recursos (incremento de versão menor)
    • fix: para correções de bugs (incremento de versão patch)
    • feat!: ou fix!: para mudanças que quebram compatibilidade (incremento de versão principal)
    • docs: para alterações de documentação
    • chore: para tarefas de manutenção
    • ci: para alterações de CI

  2. Quando commits são enviados para main:

    • O release-please cria/atualiza automaticamente um PR de release
    • O PR inclui incremento de versão e atualizações do changelog
    • Revise o PR e faça o merge quando estiver pronto

  3. Após fazer o merge do PR de release:

    • Uma nova release do GitHub é criada automaticamente
    • Uma nova tag é criada
    • O workflow publish é acionado
    • O pacote é publicado no npm