Things MCP

Things MCP

Um servidor Model Context Protocol (MCP) para integração com Things 3. Permite que o Claude Desktop e o Claude Code interajam com o Things 3 no macOS.

Recursos

• Criar tarefas e projetos com metadados completos
• Atualizar tarefas e projetos existentes
• Listar itens de qualquer lista do Things (Caixa de entrada, Hoje, Diário, Lixeira, etc.)
• Recuperar todos os projetos, áreas e tags
• Navegar para itens ou listas específicos
• Pesquisar no Things
• Execução segura de AppleScript
• Tratamento abrangente de erros

Requisitos

• macOS com Things 3 instalado
• Node.js 18 ou superior
• Esquema de URL do Things habilitado (automático no primeiro uso)

Instalação

Início rápido com npx (Recomendado)

npx github:hildersantos/things-mcp

Isso fará o download, a compilação e a inicialização automáticos do servidor MCP.

Instalação manual

1. Clone este repositório:

   git clone https://github.com/hildersantos/things-mcp.git
   cd things-mcp
   

2. Instale as dependências:

   npm install
   

3. Compile o projeto:

   npm run build
   

4. Inicie o servidor:

   npm start
   

Configuração

Configuração do Claude Desktop

1. Obtenha seu token de autenticação do Things (necessário para operações de atualização):

   • Abra Things → Configurações → Geral
   • Ative URLs do Things
   • Clique em Gerenciar → Copiar token

2. Configure o Claude Desktop:

   Abra o arquivo de configuração do Claude Desktop:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   Adicione o servidor Things MCP à seção mcpServers:

   {
     "mcpServers": {
       "things-mcp": {
         "command": "npx",
         "args": ["github:hildersantos/things-mcp"],
         "env": {
           "THINGS_AUTH_TOKEN": "your-token-here"
         }
       }
     }
   }
   

   Substitua your-token-here pelo seu token de autenticação real do Things da etapa 1.

3. Reinicie o Claude Desktop para aplicar as alterações de configuração.

Alternativa: Instalação local

Se preferir instalar localmente em vez de usar npx:

{
  "mcpServers": {
    "things-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/things-mcp/dist/index.js"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Exemplos de uso

Criar uma tarefa

Create a task "Buy milk" for today with tag "errands" in Things

Criar um projeto simples

Create a "Website Redesign" project in Things in my Work area

Criar um projeto complexo

Plan a vacation to Japan in Things with research about destinations, booking flights and hotels, 
creating a packing list, and planning daily activities

Outro exemplo de projeto

Set up a new employee onboarding project in Things with IT setup tasks, HR paperwork, 
training schedule, and first week activities

Atualizar uma tarefa

Mark task ABC-123 as completed in Things

Adicionar itens a um projeto existente

Add new tasks to my "Website Redesign" project in Things: create wireframes, design mockups, and user testing

Listar tarefas

Show me all tasks in my Things inbox

Ver projetos

List all my projects in Things

Navegar

Open my Today list in Things

Obter detalhes da tarefa

Get full details for task TBeaUrcGH1zKoMmS7wwHVD from Things

Pesquisar

Search for "meeting" in Things

Ver tarefas concluídas

Show me my completed tasks from the Things logbook

Ferramentas disponíveis

Ferramentas de criação

• things_add_todo - Criar uma tarefa com todas as opções
• things_add_project - Criar um projeto com seções (títulos), tarefas e organização hierárquica

Ferramentas de atualização (requer token de autenticação)

• things_update_todo - Atualizar uma tarefa existente usando a API JSON para suporte completo de recursos
• things_update_project - Atualizar um projeto existente usando a API JSON para suporte completo de recursos
• things_add_items_to_project - Adicionar tarefas estruturadas e títulos a um projeto existente

Ferramentas de leitura

• things_get_inbox - Listar itens da caixa de entrada
• things_get_today - Listar itens de hoje
• things_get_upcoming - Listar itens agendados
• things_get_anytime - Listar itens de qualquer momento
• things_get_someday - Listar itens de algum dia
• things_get_logbook - Listar itens concluídos
• things_get_trash - Listar itens na lixeira
• things_get_projects - Listar todos os projetos ativos
• things_get_areas - Listar todas as áreas
• things_get_tags - Listar todas as tags
• things_get_project - Listar itens em um projeto específico (requer project_id)
• things_get_area - Listar itens em uma área específica (requer area_id)
• things_get_list - Obter itens de uma lista específica pelo nome
• things_get_todo_details - Obter informações detalhadas sobre uma tarefa específica

Todas as ferramentas de listagem suportam um parâmetro opcional max_results para limitar a saída.

Ferramentas de navegação

• things_show - Navegar para item ou lista

Desenvolvimento

# Development mode with watch
npm run dev

# Run linter
npm run lint

# Format code
npm run format

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Solução de problemas

"Things 3 não parece estar em execução"

Certifique-se de que o Things 3 esteja instalado e tenha sido aberto pelo menos uma vez.

"Falha na autenticação"

Verifique se o seu THINGS_AUTH_TOKEN está configurado corretamente na configuração do MCP.

Permissões do AppleScript

Na primeira execução, o macOS pode solicitar permissão para controlar o Things. Conceda essa permissão para que o MCP funcione.

Problemas de desempenho

Use o parâmetro max_results ao listar grandes coleções:

Use things_get_projects with max_results 10

Licença

MIT

Créditos

Construído com o Model Context Protocol SDK. Things é uma marca registrada da Cultured Code GmbH & Co. KG.