Things MCP

Things MCP

Un servidor de Model Context Protocol (MCP) para la integración con Things 3. Permite que Claude Desktop y Claude Code interactúen con Things 3 en macOS.

Características

• Crear tareas y proyectos con metadatos completos
• Actualizar tareas y proyectos existentes
• Listar elementos de cualquier lista de Things (Bandeja de entrada, Hoy, Registro, Papelera, etc.)
• Obtener todos los proyectos, áreas y etiquetas
• Navegar a elementos o listas específicos
• Buscar dentro de Things
• Ejecución segura de AppleScript
• Manejo integral de errores

Requisitos

• macOS con Things 3 instalado
• Node.js 18 o posterior
• Esquema de URL de Things habilitado (automático en el primer uso)

Instalación

Inicio rápido con npx (Recomendado)

npx github:hildersantos/things-mcp

Esto descargará, compilará e iniciará automáticamente el servidor MCP.

Instalación manual

1. Clona este repositorio:

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

2. Instala las dependencias:

   npm install
   

3. Compila el proyecto:

   npm run build
   

4. Inicia el servidor:

   npm start
   

Configuración

Configuración de Claude Desktop

1. Obtén tu token de autenticación de Things (requerido para operaciones de actualización):

   • Abre Things → Ajustes → General
   • Habilita las URLs de Things
   • Haz clic en Administrar → Copiar token

2. Configura Claude Desktop:

   Abre tu archivo de configuración de Claude Desktop:

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

   Añade el servidor Things MCP a la sección mcpServers:

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

   Reemplaza your-token-here con tu token de autenticación real de Things del paso 1.

3. Reinicia Claude Desktop para aplicar los cambios de configuración.

Alternativa: Instalación local

Si prefieres instalar localmente en lugar de usar npx:

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

Ejemplos de uso

Crear una tarea

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

Crear un proyecto simple

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

Crear un proyecto complejo

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

Otro ejemplo de proyecto

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

Actualizar una tarea

Mark task ABC-123 as completed in Things

Añadir elementos a un proyecto existente

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

Listar tareas

Show me all tasks in my Things inbox

Ver proyectos

List all my projects in Things

Navegar

Open my Today list in Things

Obtener detalles de la tarea

Get full details for task TBeaUrcGH1zKoMmS7wwHVD from Things

Buscar

Search for "meeting" in Things

Ver tareas completadas

Show me my completed tasks from the Things logbook

Herramientas disponibles

Herramientas de creación

• things_add_todo - Crear una tarea con todas las opciones
• things_add_project - Crear un proyecto con secciones (encabezados), tareas y organización jerárquica

Herramientas de actualización (requieren token de autenticación)

• things_update_todo - Actualizar una tarea existente usando la API JSON para soporte completo de funciones
• things_update_project - Actualizar un proyecto existente usando la API JSON para soporte completo de funciones
• things_add_items_to_project - Añadir tareas estructuradas y encabezados a un proyecto existente

Herramientas de lectura

• things_get_inbox - Listar elementos de la bandeja de entrada
• things_get_today - Listar los elementos de hoy
• things_get_upcoming - Listar elementos programados
• things_get_anytime - Listar elementos de cualquier momento
• things_get_someday - Listar elementos de algún día
• things_get_logbook - Listar elementos completados
• things_get_trash - Listar elementos en la papelera
• things_get_projects - Listar todos los proyectos activos
• things_get_areas - Listar todas las áreas
• things_get_tags - Listar todas las etiquetas
• things_get_project - Listar elementos en un proyecto específico (requiere project_id)
• things_get_area - Listar elementos en un área específica (requiere area_id)
• things_get_list - Obtener elementos de una lista específica por nombre
• things_get_todo_details - Obtener información detallada sobre una tarea específica

Todas las herramientas de lista admiten un parámetro opcional max_results para limitar la salida.

Herramientas de navegación

• things_show - Navegar a un elemento o lista

Desarrollo

# 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

Solución de problemas

"Parece que Things 3 no está en ejecución"

Asegúrate de que Things 3 esté instalado y se haya abierto al menos una vez.

"Error de autenticación"

Verifica que tu THINGS_AUTH_TOKEN esté configurado correctamente en la configuración de MCP.

Permisos de AppleScript

En el primer inicio, macOS puede solicitar permiso para controlar Things. Concede este permiso para que MCP funcione.

Problemas de rendimiento

Usa el parámetro max_results al listar colecciones grandes:

Use things_get_projects with max_results 10

Licencia

MIT

Créditos

Construido con el Model Context Protocol SDK. Things es una marca comercial de Cultured Code GmbH & Co. KG.