TickTick

Gerencie tarefas, projetos e hábitos usando a API do TickTick.

Documentação

Servidor MCP TickTick

Servidor MCP para a API TickTick, permitindo gerenciamento de tarefas, organização de projetos, rastreamento de hábitos e muito mais.

Recursos

✅ Gerenciamento de Tarefas: Criar, ler, atualizar e excluir tarefas com todas as propriedades disponíveis
📊 Gerenciamento de Projetos: Criar, ler, atualizar e excluir projetos com visualizações personalizáveis
📋 Suporte a Subtarefas: Suporte completo para gerenciar subtarefas dentro de tarefas pai
🔄 Controle Completo de Tarefas: Definir prioridades, datas de vencimento, lembretes e regras de recorrência
🔐 Autenticação OAuth: Implementação completa de OAuth2 para acesso seguro à API
⚠️ Tratamento Abrangente de Erros: Mensagens de erro claras para problemas comuns

Ferramentas

get_task_by_ids
- Obter uma tarefa específica pelo ID do projeto e ID da tarefa
- Entradas:
  - projectId (string): Identificador do projeto
  - taskId (string): Identificador da tarefa
- Retorna: Objeto de tarefa correspondente a TickTickTaskSchema
create_task
- Criar uma nova tarefa em um projeto
- Entradas:
  - title (string): Título da tarefa
  - projectId (string): ID do projeto
  - content (string opcional): Conteúdo da tarefa
  - desc (string opcional): Descrição da tarefa
  - isAllDay (booleano opcional): É tarefa de dia inteiro
  - startDate (string opcional): Data de início da tarefa no formato "yyyy-MM-dd'T'HH:mm:ssZ"
  - dueDate (string opcional): Data de vencimento da tarefa no formato "yyyy-MM-dd'T'HH:mm:ssZ"
  - timeZone (string opcional): Fuso horário da tarefa (ex.: "America/Los_Angeles")
  - reminders (string[] opcional): Lista de gatilhos de lembrete no formato iCalendar
  - repeatFlag (string opcional): Sinalizador de repetição da tarefa no formato iCalendar
  - priority (número opcional): Prioridade da tarefa (Nenhuma: 0, Baixa: 1, Média: 3, Alta: 5)
  - sortOrder (string opcional): Ordem de classificação da tarefa
  - items (array opcional): Lista de subtarefas com:
    - title (string): Título do item da subtarefa
    - startDate (string opcional): Data da subtarefa no formato "yyyy-MM-dd'T'HH:mm:ssZ"
    - isAllDay (booleano opcional): É item de subtarefa de dia inteiro
    - sortOrder (número opcional): Ordem de classificação do item da subtarefa
    - timeZone (string opcional): Fuso horário da subtarefa
    - status (número opcional): Status de conclusão (Normal: 0, Concluída: 1)
    - completedTime (string opcional): Horário de conclusão no formato "yyyy-MM-dd'T'HH:mm:ssZ"
- Retorna: Objeto de tarefa criado correspondente a TickTickTaskSchema
update_task
- Atualizar uma tarefa existente
- Entradas:
  - taskId (string): Identificador da tarefa - Caminho
  - id (string): Identificador da tarefa - Corpo
  - projectId (string): ID do projeto
  - Todos os campos opcionais de create_task
- Retorna: Objeto de tarefa atualizado correspondente a TickTickTaskSchema
complete_task
- Marcar uma tarefa como concluída
- Entradas:
  - taskId (string): Identificador da tarefa
  - projectId (string): Identificador do projeto
- Retorna: void
delete_task
- Excluir uma tarefa de um projeto
- Entradas:
  - taskId (string): Identificador da tarefa
  - projectId (string): Identificador do projeto
- Retorna: void
get_user_projects
- Obter todos os projetos do usuário autenticado
- Entradas: Nenhuma
- Retorna: Array de objetos de projeto correspondentes a TickTickProjectSchema
get_project_by_id
- Obter um projeto específico por ID
- Entradas:
  - projectId (string): Identificador do projeto
- Retorna: Objeto de projeto correspondente a TickTickProjectSchema
get_project_with_data
- Obter detalhes do projeto juntamente com tarefas e colunas
- Entradas:
  - projectId (string): Identificador do projeto
- Retorna: Objeto contendo:
  - project: Objeto de projeto correspondente a TickTickProjectSchema
  - tasks: Array de objetos de tarefa correspondentes a TickTickTaskSchema
  - columns: Array opcional de objetos de coluna com:
    - id (string opcional)
    - projectId (string opcional)
    - name (string opcional)
    - sortOrder (número opcional)
create_project
- Criar um novo projeto
- Entradas:
  - name (string): Nome do projeto
  - color (string opcional): Cor do projeto (padrão: '#4772FA')
  - viewMode (string opcional): Modo de visualização ('list', 'kanban', 'timeline') (padrão: 'list')
  - kind (string opcional): Tipo de projeto ('TASK', 'NOTE') (padrão: 'TASK')
- Retorna: Objeto de projeto criado correspondente a TickTickProjectSchema
update_project
- Atualizar um projeto existente
- Entradas:
  - projectId (string): Identificador do projeto
  - name (string opcional): Nome do projeto
  - color (string opcional): Cor do projeto
  - sortOrder (número opcional): Ordem de classificação do projeto
  - viewMode (string opcional): Modo de visualização ('list', 'kanban', 'timeline')
  - kind (string opcional): Tipo de projeto ('TASK', 'NOTE')
- Retorna: Objeto de projeto atualizado correspondente a TickTickProjectSchema
delete_project
- Excluir um projeto
- Entradas:
  - projectId (string): Identificador do projeto
- Retorna: void

Referências de Esquema

TickTickTaskSchema: Define a estrutura para objetos de tarefa, incluindo:
- Propriedades básicas da tarefa (id, título, descrição)
- Configurações de datas e horários
- Prioridade e status
- Itens de checklist e subtarefas
TickTickProjectSchema: Define a estrutura para objetos de projeto, incluindo:
- Identificação e nomenclatura do projeto
- Configurações de exibição (cor, modo de visualização)
- Permissões e organização

Propriedades das Tarefas

Ao criar ou atualizar tarefas, você pode incluir estas propriedades:

Níveis de Prioridade:
- 0: Nenhuma
- 1: Baixa
- 3: Média
- 5: Alta
Valores de Status:
- 0: Normal (não concluída)
- 2: Concluída
Formato de Lembrete:
- Exemplo: ["TRIGGER:P0DT9H0M0S", "TRIGGER:PT0S"]
- Segue o formato TRIGGER do iCalendar
Regras de Recorrência (repeatFlag):
- Exemplo: "RRULE:FREQ=DAILY;INTERVAL=1"
- Usa regras de recorrência RFC 5545
Formato de Data:
- Formato ISO 8601: "yyyy-MM-dd'T'HH:mm:ssZ"
- Exemplo: "2019-11-13T03:00:00+0000"

Propriedades dos Projetos

Ao criar ou atualizar projetos, você pode usar estas propriedades:

Modos de Visualização:
- "list": Visualização de lista padrão
- "kanban": Visualização de quadro Kanban
- "timeline": Visualização de linha do tempo
Tipos de Projeto:
- "TASK": Projeto orientado a tarefas
- "NOTE": Projeto orientado a notas

Configuração

Autenticação OAuth

Para habilitar a autenticação OAuth com TickTick, você precisará registrar seu aplicativo e obter credenciais da API:

Crie uma conta no Portal do Desenvolvedor TickTick
Registre um novo aplicativo
Defina a URL de redirecionamento OAuth para: http://localhost:8000/callback
Copie o Client ID (TICKTICK_CLIENT_ID) e o Client Secret (TICKTICK_CLIENT_SECRET) gerados

Fluxo de Autorização na Primeira Vez

Ao usar o servidor MCP TickTick pela primeira vez:

Você será solicitado a autorizar o aplicativo
Uma janela do navegador será aberta com a página de login do TickTick
Após o login, você será solicitado a conceder permissões
O token de acesso será exibido na página
Copie este token e defina-o como a variável de ambiente TICKTICK_ACCESS_TOKEN

Gerar Token de Acesso

Quando você precisar gerar um novo token de acesso (seja para a configuração inicial ou quando o token expirar), siga estes passos:

Configure suas credenciais usando um destes métodos:

Opção 1: Arquivo .env (Recomendado)

Crie um arquivo .env na raiz do seu projeto:
```
TICKTICK_CLIENT_ID="<YOUR_CLIENT_ID>"
TICKTICK_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
```
Em seguida, carregue-o:
```
source .env
```
Este método é recomendado porque:
- As credenciais persistem entre sessões de terminal
- Mais fácil gerenciar múltiplas configurações
- Menos propenso a vazamentos no histórico do shell
- Pode ser facilmente feito backup (lembre-se de excluir do controle de versão)
Opção 2: Variáveis de Ambiente do Terminal

Use aspas simples se suas credenciais contiverem caracteres especiais. Observe que estas variáveis persistirão apenas na sua sessão atual do terminal:
```
export TICKTICK_CLIENT_ID='<YOUR_CLIENT_ID>'
export TICKTICK_CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
```
Execute o comando de autenticação:

Se estiver usando o pacote publicado:
```
npx @alexarevalo.ai/mcp-server-ticktick ticktick-auth
```
Se estiver executando o servidor MCP localmente:
```
npm run start:auth
```
O processo irá:
- Abrir seu navegador padrão
- Direcioná-lo para a página de login do TickTick
- Solicitar as permissões necessárias
- Gerar e exibir seu token de acesso

Salve o token de acesso:

echo "TICKTICK_ACCESS_TOKEN=\"<GENERATED_TOKEN>\"" >> .env
source .env

Dicas de Segurança:

Adicione .env ao seu arquivo .gitignore

Nunca envie credenciais para o controle de versão

Tokens de acesso expiram após 180 dias - você precisará regenerá-los

Uso com Claude Desktop

Para usar com Claude Desktop, adicione o seguinte ao seu claude_desktop_config.json:

NPX

{
  "mcpServers": {
    "ticktick": {
      "command": "npx",
      "args": ["-y", "@alexarevalo.ai/mcp-server-ticktick"],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "ticktick": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TICKTICK_CLIENT_ID",
        "-e",
        "TICKTICK_CLIENT_SECRET",
        "-e",
        "TICKTICK_ACCESS_TOKEN",
        "mcp/ticktick"
      ],
      "env": {
        "TICKTICK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "TICKTICK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "TICKTICK_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Instalação via Smithery

Para instalar o ticktick-mcp-server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @alexarevalo9/ticktick-mcp-server --client claude

Build

Build Docker:

docker build -t mcp/ticktick -f src/ticktick/Dockerfile .

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.