Todoist

Integra com a API do Todoist para gerenciar suas tarefas e projetos.

GitHub
1

Documentação

Servidor MCP Todoist

Um servidor Model Context Protocol (MCP) que fornece integração com a API do Todoist para assistentes de IA.

Visão Geral

O Servidor MCP Todoist permite que assistentes de IA interajam com o Todoist, possibilitando que gerenciem tarefas e projetos em nome dos usuários. Este servidor implementa o Model Context Protocol (MCP), fornecendo uma interface padronizada para que sistemas de IA acessem a funcionalidade do Todoist.

Recursos

  • Gerenciamento de Tarefas

    • Obter regras de filtro e exemplos para filtragem de tarefas
    • Obter tarefas com opções de filtragem
    • Obter detalhes de tarefas
    • Criar novas tarefas
    • Atualizar tarefas existentes
    • Marcar tarefas como concluídas
    • Excluir tarefas

  • Gerenciamento de Projetos

    • Obter todos os projetos
    • Obter detalhes de projetos

Instalação

Pré-requisitos

  • Go 1.21 ou posterior (para compilar a partir do código-fonte)
  • Docker (para instalação via Docker)
  • Token da API do Todoist

Compilando a partir do Código-Fonte

  1. Clone o repositório:
git clone https://github.com/naotama2002/todoist-go-mcp-server.git
cd todoist-go-mcp-server
  1. Instale as dependências:
go mod download
  1. Compile o binário:
make build

Usando Docker

Você também pode executar o todoist-mcp-server usando Docker, o que proporciona um ambiente consistente e uma implantação mais fácil.

Baixar do GitHub Container Registry

# Pull the latest image
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/todoist-go-mcp-server:{TAG}

Compilar localmente

# Build the Docker image
docker build -t todoist-mcp-server .

Configuração

Configure seu token da API do Todoist:

Crie um arquivo .envrc no diretório raiz com o seguinte conteúdo:

export TODOIST_API_TOKEN=your_todoist_api_token

Se você estiver usando direnv, execute:

direnv allow

Alternativamente, você pode definir a variável de ambiente diretamente:

export TODOIST_API_TOKEN=your_todoist_api_token

Uso

Executando o Servidor

Uso do Binário

Modo HTTP

Execute o servidor em modo HTTP:

go run cmd/todoist-mcp-server/main.go --mode http --addr :8080

Ou usando o binário compilado:

./build/todoist-mcp-server --mode http --addr :8080
Modo de Entrada/Saída Padrão

Execute o servidor em modo stdio para integração com clientes MCP:

go run cmd/todoist-mcp-server/main.go --mode stdio

Ou usando o binário compilado:

./build/todoist-mcp-server --mode stdio

Uso do Docker

Modo HTTP
# Basic usage with Docker
docker run --rm -it -p 8080:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

# With custom port
docker run --rm -it -p 3000:3000 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :3000

# Using locally built image
docker run --rm -it -p 8080:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  todoist-mcp-server --mode http --addr :8080
Modo de Entrada/Saída Padrão
# For stdio mode (used with MCP clients)
docker run --rm -i -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

# Using locally built image
docker run --rm -i -e TODOIST_API_TOKEN=your_todoist_api_token \
  todoist-mcp-server --mode stdio

Opções de Linha de Comando

O servidor suporta as seguintes opções de linha de comando:

  • --mode <mode>: Modo do servidor, 'http' ou 'stdio' (padrão: "http")
    • http: Executar como servidor HTTP
    • stdio: Executar usando entrada/saída padrão para comunicação MCP
  • --addr <address>: Endereço para escutar no modo HTTP (padrão: ":8080")
  • --token <token>: Token da API do Todoist (também pode ser definido pela variável de ambiente TODOIST_API_TOKEN)

Exemplos:

# Run HTTP server on port 3000
go run cmd/todoist-mcp-server/main.go --mode http --addr :3000

# Run with a specific Todoist API token
go run cmd/todoist-mcp-server/main.go --mode http --token your_todoist_api_token

# Run in stdio mode
go run cmd/todoist-mcp-server/main.go --mode stdio

Testando com o Cliente MCP

Você pode testar o servidor usando o cliente de teste incluído:

go run cmd/test-mcp-client/main.go

Ferramentas Disponíveis

Gerenciamento de Tarefas

todoist_get_task_filter_rules

Obter regras de filtro e exemplos para filtros de tarefas do Todoist. Esta ferramenta ajuda a traduzir consultas em linguagem natural para a sintaxe de filtro do Todoist para a ferramenta todoist_get_tasks.

Parâmetros: Nenhum

Exemplo de resposta (formato Markdown):

# Introduction to Filters

Filters in Todoist are custom views that display tasks based on specific criteria. You can filter tasks by name, date, project, label, priority, creation date, and more.

## Creating Filters

1. Select "Filters & Labels" in the sidebar
2. Click the add icon next to Filters
3. Enter a name for your filter and change its color (optional)
4. Enter your filter query
5. Click "Add" to save your filter

## Filter Symbols

| Symbol | Meaning | Example |
|--------|---------|--------|
| \| | OR | today \| overdue |
| & | AND | today & p1 |
| ! | NOT | !subtask |
| () | Priority processing | (today \| overdue) & #work |

## Advanced Queries

### Keyword-Based Filters

| Description | Query |
|-------------|-------|
| Tasks containing "meeting" | search: meeting |
| Tasks containing "meeting" scheduled for today | search: meeting & today |

### Date-Based Filters

| Description | Query |
|-------------|-------|
| Tasks for a specific date | date: jan 3 |
| Tasks before a specific date | before: may 5 |
| Tasks with no date | no date |

## Useful Filter Examples

| Description | Query |
|-------------|-------|
| Overdue or today's tasks in "Work" project | (today \| overdue) & #work |
| Tasks with no date | no date |
| Tasks with @waiting label in the next 7 days | 7 days & @waiting |


#### `todoist_get_tasks`

Get a list of tasks with filtering options.

Parameters:
- `projectId` (string, optional): Filter tasks by project ID
- `filter` (string, optional): Todoist filter query using the Todoist filter syntax

Example:
```json
{
  "projectId": "2203306141",
  "filter": "today"
}

todoist_get_task

Obter detalhes de uma tarefa específica.

Parâmetros:

  • id (string, obrigatório): O identificador único da tarefa

Exemplo:

{
  "id": "2995104339"
}

todoist_create_task

Criar uma nova tarefa.

Parâmetros:

  • content (string, obrigatório): O conteúdo da tarefa
  • description (string, opcional): Descrição detalhada ou notas para a tarefa
  • projectId (string, opcional): ID do projeto para atribuir a tarefa
  • parentId (string, opcional): ID da tarefa pai para criar subtarefas
  • order (inteiro, opcional): Valor de ordem para posicionar a tarefa
  • priority (inteiro, opcional): Prioridade da tarefa: 1 (normal), 2 (média), 3 (alta), 4 (urgente)
  • dueString (string, opcional): Data de vencimento em linguagem natural, ex.: 'hoje', 'amanhã'
  • dueDate (string, opcional): Data de vencimento no formato AAAA-MM-DD
  • dueDatetime (string, opcional): Data e hora de vencimento no formato RFC3339

Exemplo:

{
  "content": "Buy groceries",
  "description": "Need to buy milk, eggs, and bread",
  "projectId": "2203306141",
  "priority": 2,
  "dueString": "tomorrow at 10am"
}

todoist_update_task

Atualizar uma tarefa existente.

Parâmetros:

  • id (string, obrigatório): O identificador único da tarefa a ser atualizada
  • content (string, opcional): O novo conteúdo da tarefa
  • description (string, opcional): Descrição detalhada ou notas para a tarefa
  • priority (inteiro, opcional): Prioridade da tarefa: 1 (normal), 2 (média), 3 (alta), 4 (urgente)
  • dueString (string, opcional): Data de vencimento em linguagem natural
  • dueDate (string, opcional): Data de vencimento no formato AAAA-MM-DD
  • dueDatetime (string, opcional): Data e hora de vencimento no formato RFC3339

Exemplo:

{
  "id": "2995104339",
  "content": "Buy groceries and household items",
  "priority": 1
}

todoist_close_task

Marcar uma tarefa como concluída.

Parâmetros:

  • id (string, obrigatório): O identificador único da tarefa a ser marcada como concluída

Exemplo:

{
  "id": "2995104339"
}

todoist_delete_task

Excluir uma tarefa.

Parâmetros:

  • id (string, obrigatório): O identificador único da tarefa a ser excluída

Exemplo:

{
  "id": "2995104339"
}

Gerenciamento de Projetos

todoist_get_projects

Obter uma lista de todos os projetos.

Parâmetros: Nenhum

todoist_get_project

Obter detalhes de um projeto específico.

Parâmetros:

  • id (string, obrigatório): O identificador único do projeto

Exemplo:

{
  "id": "2203306141"
}

Integração com o Claude Desktop

Para usar o Servidor MCP Todoist com o Claude Desktop, você precisa adicioná-lo à configuração do seu Claude Desktop.

Baixar dos Lançamentos do GitHub

A maneira mais fácil de começar é baixar um binário pré-compilado da página de Lançamentos do GitHub:

  1. Vá para a página de Lançamentos e baixe o lançamento mais recente para sua plataforma:

    • Linux: todoist-mcp-server_Linux_x86_64.tar.gz ou todoist-mcp-server_Linux_arm64.tar.gz
    • macOS: todoist-mcp-server_Darwin_x86_64.tar.gz ou todoist-mcp-server_Darwin_arm64.tar.gz
    • Windows: todoist-mcp-server_Windows_x86_64.zip

  2. Extraia o arquivo para obter o binário todoist-mcp-server:

    # For Linux/macOS
tar -xzf todoist-mcp-server_*_*.tar.gz

# For Windows
# Extract the zip file using Windows Explorer or a tool like 7-Zip

  3. Torne o binário executável (somente Linux/macOS):

    chmod +x todoist-mcp-server

  4. Opcionalmente, mova o binário para um local no seu PATH:

    # Linux/macOS
sudo mv todoist-mcp-server /usr/local/bin/

# Windows
# Move the .exe file to a location in your PATH

Compilar a partir do código-fonte

Alternativamente, você pode compilar o binário a partir do código-fonte:

# Build the binary
make build

Configuração

Adicione o Servidor MCP Todoist à configuração do seu Claude Desktop:

Modo HTTP

  1. Execute o Servidor MCP Todoist em modo HTTP:
todoist-mcp-server --mode http --addr :8080
  1. Adicione a seguinte configuração às configurações do seu Claude Desktop:
{
  "name": "Todoist",
  "description": "Manage Todoist tasks and projects",
  "endpoint": "http://localhost:8080",
  "tools": [
    {
      "name": "todoist_get_task_filter_rules",
      "description": "Get filter rules and examples for Todoist task filters"
    },
    {
      "name": "todoist_get_tasks",
      "description": "Get a list of tasks with filtering options"
    },
    {
      "name": "todoist_get_task",
      "description": "Get details of a specific task"
    },
    {
      "name": "todoist_create_task",
      "description": "Create a new task"
    },
    {
      "name": "todoist_update_task",
      "description": "Update an existing task"
    },
    {
      "name": "todoist_close_task",
      "description": "Mark a task as completed"
    },
    {
      "name": "todoist_delete_task",
      "description": "Delete a task"
    },
    {
      "name": "todoist_get_projects",
      "description": "Get a list of all projects"
    },
    {
      "name": "todoist_get_project",
      "description": "Get details of a specific project"
    }
  ]
}

Modo Stdio

Usando Binário

Claude Desktop / Cline, Roo Cline / Windsurf

{
  "mcpServers": {
    "todoist": {
      "command": "/path/to/todoist-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "TODOIST_API_TOKEN": "<YOUR_TODOIST_API_TOKEN>"
      }
    }
  }
}

VSCode

{
  "mcp": {
    "servers": {
      "todoist": {
        "command": "/path/to/todoist-mcp-server",
        "args": ["--mode", "stdio"],
        "env": {
          "TODOIST_API_TOKEN": "<YOUR_TODOIST_API_TOKEN>"
        }
      }
    }
  }
}
Usando Docker

Claude Desktop / Cline, Roo Cline / Windsurf

{
  "mcpServers": {
    "todoist": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TODOIST_API_TOKEN=<YOUR_TODOIST_API_TOKEN>",
        "ghcr.io/naotama2002/todoist-go-mcp-server:latest",
        "--mode",
        "stdio"
      ]
    }
  }
}

VSCode

{
  "mcp": {
    "servers": {
      "todoist": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e",
          "TODOIST_API_TOKEN=<YOUR_TODOIST_API_TOKEN>",
          "ghcr.io/naotama2002/todoist-go-mcp-server:latest",
          "--mode",
          "stdio"
        ]
      }
    }
  }
}

Substitua /path/to/todoist-mcp-server pelo caminho real do binário e <YOUR_TODOIST_API_TOKEN> pelo seu token da API do Todoist.

  1. No Claude Desktop, vá para Configurações > Ferramentas > Adicionar Ferramenta e cole a configuração JSON apropriada.

  2. Salve a configuração e reinicie o Claude Desktop, se necessário.

Agora você pode pedir ao Claude para gerenciar suas tarefas e projetos do Todoist usando linguagem natural.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Solução de Problemas

Problemas com Docker

Porta Já em Uso

Se você receber um erro de "porta já em uso", pare o serviço conflitante ou use uma porta diferente:

# Use a different port
docker run --rm -it -p 3335:8080 -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode http --addr :8080

Problemas de Rede com Clientes MCP

Se os clientes MCP não conseguirem se conectar ao contêiner Docker, tente usar rede do host:

# Use host networking mode
docker run --rm -i --net=host -e TODOIST_API_TOKEN=your_todoist_api_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

Problemas com Variáveis de Ambiente

Certifique-se de que seu token da API do Todoist esteja configurado corretamente:

# Check if the token is set correctly
docker run --rm -i -e TODOIST_API_TOKEN=your_actual_token \
  ghcr.io/naotama2002/todoist-go-mcp-server:latest --mode stdio

Limpar Dados de Autenticação

Se você estiver tendo problemas com autenticação, verifique seu token da API do Todoist:

  1. Vá para Integrações do Todoist
  2. Copie seu token da API
  3. Certifique-se de que ele esteja configurado corretamente no seu ambiente

Licença

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

Agradecimentos

Desenvolvimento

Estrutura do Projeto

todoist-go-mcp-server/
├── cmd/
│   ├── test-client/        # Test client for the Todoist API
│   ├── test-mcp-client/    # Test client for the MCP server
│   └── todoist-mcp-server/ # Main MCP server application
├── docs/                   # Documentation
├── pkg/
│   ├── log/                # Logging utilities
│   ├── todoist/            # Todoist API client and tools
│   └── toolsets/           # MCP toolset definitions
└── todo/                   # Implementation plans and notes

Executando Testes

make test