Things

Interaja com seus dados de gerenciamento de tarefas no aplicativo Things.

GitHub
616

Documentação

Things MCP Server

Este servidor Model Context Protocol (MCP) permite que você use o Claude Desktop para interagir com seus dados de gerenciamento de tarefas no Things 3 da Cultured Code. Você pode pedir ao Claude para criar tarefas, analisar projetos, ajudar a gerenciar prioridades e muito mais.

Este servidor utiliza a biblioteca Things.py e o Things URL Scheme.

Things Server MCP server

Apoie o Projeto

Se você achar este projeto útil, considere apoiar seu desenvolvimento:

ko-fi

Recursos

  • Acesso a todas as principais listas do Things (Inbox, Today, Upcoming, etc.)
  • Gerenciamento de projetos e áreas
  • Operações com tags
  • Recursos avançados de busca
  • Itens recentes
  • Informações detalhadas dos itens, incluindo checklists
  • Suporte a dados aninhados (projetos dentro de áreas, tarefas dentro de projetos)
  • Filtro de projetos Someday: tarefas em projetos Someday são automaticamente excluídas das visualizações Today, Upcoming e Anytime, correspondendo ao comportamento da interface do Things

Instalação

Pré-requisitos

  • macOS (Things 3 é exclusivo para Mac)
  • Aplicativo Things 3 com "Enable Things URLs" ativado (Settings → General)
  • Um cliente MCP, como Claude Desktop ou Claude Code
  • Gerenciador de pacotes Python uv: brew install uv

Instalação via uvx (Qualquer Cliente MCP)

O Things MCP é publicado no PyPI e pode ser executado diretamente com uvx:

uvx things-mcp

Configure seu cliente MCP para usar uvx com things-mcp como argumento.

Claude Desktop

Opção 1: Instalação com um clique (Recomendado)

  1. Baixe o arquivo mais recente da página de releases
  2. Clique duas vezes no arquivo .mcpb
  3. Pronto!

Opção 2: Configuração Manual

  1. Vá para Claude → Settings → Developer → Edit Config
  2. Adicione o servidor Things:
{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": ["things-mcp"]
    }
  }
}
  1. Salve e reinicie o Claude Desktop

Claude Code

claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'

Para disponibilizá-lo globalmente (em todos os projetos), adicione -s user:

claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'

Verifique se está funcionando

Após a instalação:

  • Se estiver usando o Claude Desktop, você deve ver "Things MCP" na lista "Search and tools"
  • Tente perguntar: "O que há na minha caixa de entrada do Things?"

Exemplos de Uso com o Claude Desktop

  • "O que está na minha lista de tarefas hoje?"
  • "Crie uma tarefa para arrumar as malas das minhas férias na praia na próxima semana, incluindo um checklist de arrumação."
  • "Avalie minhas tarefas atuais usando a matriz de Eisenhower."
  • "Ajude-me a fazer uma revisão semanal no estilo GTD usando o Things."
  • "Mostre-me tarefas que não foram modificadas há mais de um mês."

Dicas

  • Crie um projeto no Claude com instruções personalizadas que expliquem como você usa o Things e organiza áreas, projetos, tags, etc. Diga ao Claude quais informações você deseja incluir ao criar uma nova tarefa (por exemplo, pedir que ele inclua detalhes relevantes na descrição da tarefa pode ser útil).
  • Tente adicionar outro servidor MCP que dê ao Claude acesso ao seu calendário. Isso permitirá que você peça ao Claude para reservar horários no seu calendário para tarefas específicas, criar tarefas a partir de eventos futuros do calendário (por exemplo, preparação para uma reunião), etc.
  • Use a idade das tarefas para identificar itens desatualizados: "Quais tarefas na minha lista Anytime têm mais de 2 semanas?"

Ferramentas Disponíveis

Visualizações de Lista

  • get-inbox - Obter tarefas da Inbox
  • get-today - Obter tarefas com vencimento hoje
  • get-upcoming - Obter tarefas futuras
  • get-anytime - Obter tarefas da lista Anytime
  • get-someday - Obter tarefas da lista Someday, incluindo tarefas em projetos Someday
  • get-logbook - Obter tarefas concluídas
  • get-trash - Obter tarefas na lixeira

Operações Básicas

  • get-todos - Obter tarefas, opcionalmente filtradas por projeto
  • get-projects - Obter todos os projetos
  • get-areas - Obter todas as áreas

Operações com Tags

  • get-tags - Obter todas as tags
  • get-tagged-items - Obter itens com uma tag específica
  • get-tag-usage - Relatar quantos itens usam cada tag, ordenados por uso; sinalizar tags não utilizadas para limpeza

Operações de Busca

  • search-todos - Busca simples por título/notas
  • search-advanced - Busca avançada com múltiplos filtros

Operações Baseadas em Tempo

  • get-recent - Obter itens criados recentemente

Operações do Things URL Scheme

  • add-todo - Criar uma nova tarefa
  • add-project - Criar um novo projeto
  • add-area - Criar uma nova área (via AppleScript; o Things URL scheme não possui comando add-area)
  • update-area - Atualizar uma área existente: renomear ou definir tags (via AppleScript)
  • update-todo - Atualizar uma tarefa existente
  • bulk-update-todos - Aplicar a mesma atualização a várias tarefas em uma única operação
  • update-project - Atualizar um projeto existente
  • show-item - Mostrar um item ou lista específico no Things
  • search-items - Buscar itens no Things

Parâmetros das Ferramentas

Paginação (a maioria das ferramentas de leitura)

As ferramentas de leitura de lista/busca (get-inbox, get-today, get-upcoming, get-anytime, get-someday, get-logbook, get-trash, get-todos, get-projects, get-areas, get-tags, get-tagged-items, get-headings, search-todos, search-advanced, get-recent) aceitam paginação opcional:

  • limit - Número máximo de itens a retornar (padrão: todos; get-logbook tem padrão de 50)
  • offset - Número de itens a pular do início (padrão: 0)

Quando nenhum é definido, a saída permanece inalterada. Quando definidos, um cabeçalho Showing X-Y of Z items é adicionado no início para que você saiba quanto mais há. Um offset além do final é relatado de forma distinta de um resultado vazio.

Essas mesmas ferramentas de leitura também retornam conteúdo estruturado junto com o texto legível: os clientes MCP recebem os dicionários brutos dos itens mais count/total/offset/limit em structured_content, para que os dados possam ser consumidos programaticamente sem analisar o texto formatado.

get-todos

  • project_uuid (opcional) - Filtrar tarefas por projeto
  • include_items (opcional, padrão: true) - Incluir itens de checklist

get-projects / get-areas / get-tags

  • include_items (opcional, padrão: false) - Incluir itens contidos

search-advanced

  • status - Filtrar por status (incomplete/completed/canceled)
  • start_date - Filtrar por data de início (YYYY-MM-DD)
  • deadline - Filtrar por prazo (YYYY-MM-DD)
  • tag - Filtrar por tag
  • area - Filtrar por UUID da área
  • type - Filtrar por tipo de item (to-do/project/heading)
  • last - Filtrar por data de criação (ex.: '3d' para os últimos 3 dias, '1w' para a última semana)

get-recent

  • period - Período de tempo (ex.: '3d', '1w', '2m', '1y')

get-logbook

  • period (opcional, padrão: '7d') - Janela de retrospectiva por data de conclusão. Aceita d/w/m/y (ex.: '3d', '1w', '2m', '1y'); meses ≈ 30 dias, anos ≈ 365 dias
  • limit (opcional, padrão: 50) - Número máximo de itens concluídos a retornar

get-tag-usage

  • only_unused (opcional, padrão: false) - Retornar apenas tags que nenhum item referencia (candidatas a limpeza)

update-todo (checklist & tags)

  • tags - Substituir todas as tags da tarefa
  • add_tags - Adicionar tags sem remover as existentes
  • checklist_items - Substituir todo o checklist por esta lista
  • prepend_checklist_items - Adicionar estes itens ao topo do checklist
  • append_checklist_items - Adicionar estes itens ao final do checklist

bulk-update-todos

Aplica a mesma alteração a todas as tarefas em ids em uma única operação. Requer que o token de autenticação do Things esteja habilitado (Things → Settings → General → Enable Things URLs → Manage); o servidor o lê automaticamente.

  • ids (obrigatório) - Lista de UUIDs de tarefas a atualizar
  • list / list_id - Mover todas para um projeto/área (por título ou UUID)
  • tags / add_tags - Substituir ou adicionar tags em todas
  • when - Reagendar todas (palavra-chave ou YYYY-MM-DD)
  • deadline - Definir prazo em todas (YYYY-MM-DD)
  • heading / heading_id - Mover todas para um cabeçalho (por título ou UUID)
  • completed / canceled - Marcar todas como concluídas ou canceladas

Agendamento com Lembretes (add-todo, add-project, update-todo, update-project)

  • when - Aceita múltiplos formatos:
    • Palavras-chave: today, tomorrow, evening, anytime, someday
    • Data: YYYY-MM-DD (ex.: 2024-01-15)
    • DataHora com lembrete: YYYY-MM-DD@HH:MM (ex.: 2024-01-15@14:30)

Solução de Problemas

Se não estiver funcionando:

  1. Certifique-se de que o Things 3 está instalado e foi aberto pelo menos uma vez

    • O banco de dados do Things precisa existir para que o servidor funcione

  2. Verifique se "Enable Things URLs" está ativado

    • Abra Things → Settings → General → Enable Things URLs

  3. O Claude Desktop não consegue encontrar uvx

    • Instale o uv globalmente com o Homebrew (brew install uv)
    • Alternativa: Use o caminho completo para uvx na sua configuração. Encontre-o com which uvx (normalmente /Users/USERNAME/.local/bin/uvx)

Desenvolvimento

Executando Testes

O projeto inclui uma suíte abrangente de testes unitários para os módulos de URL scheme e formatação.

# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run a specific test file
uv run pytest tests/test_url_scheme.py

# Run tests matching a pattern
uv run pytest -k "test_add_todo"

Teste de Integração MCP

O projeto inclui um plano de teste de integração que pode ser executado pelo Claude (via Claude Cowork ou Claude Code) para verificar se todas as ferramentas MCP funcionam corretamente com um banco de dados Things ativo.

Consulte docs/mcp_integration_test_plan.md para o plano de teste completo.

Estrutura do Projeto

things-mcp/
├── src/things_mcp/      # Main package
│   ├── __init__.py      # Package exports
│   ├── __main__.py      # Entry point for python -m
│   ├── server.py        # MCP server implementation
│   ├── url_scheme.py    # Things URL scheme implementation
│   └── formatters.py    # Data formatting utilities
├── tests/               # Unit tests
│   ├── conftest.py      # Test fixtures and configuration
│   ├── test_url_scheme.py
│   ├── test_formatters.py
│   ├── test_someday_filtering.py
│   └── test_mcp_server_filtering.py
├── docs/                # Documentation
│   └── mcp_integration_test_plan.md  # Claude-executable integration test
├── manifest.json        # MCPB package manifest
├── build_mcpb.sh        # MCPB package build script
├── pyproject.toml       # Project dependencies, build config, and pytest config
├── .env.example         # Sample environment configuration
└── run.sh               # Convenience runner script

Transporte HTTP

Por padrão, o servidor usa transporte stdio para comunicação com clientes MCP. Para cenários de acesso remoto, você pode executar o servidor com transporte HTTP.

Configuração

Defina estas variáveis de ambiente para habilitar o transporte HTTP:

VariávelPadrãoDescrição
THINGS_MCP_TRANSPORTstdioTipo de transporte: stdio ou http
THINGS_MCP_HOST127.0.0.1Endereço de bind do servidor HTTP
THINGS_MCP_PORT8000Porta do servidor HTTP

Exemplo

# Using uvx
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uvx things-mcp

# Or from source
THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uv run things-mcp

Consulte .env.example para um arquivo de configuração de exemplo.