Things

Interactúa con tus datos de gestión de tareas en la aplicación Things.

Documentación

Servidor MCP de Things

Este servidor de Model Context Protocol (MCP) te permite usar Claude Desktop para interactuar con tus datos de gestión de tareas en Things 3 de Cultured Code. Puedes pedirle a Claude que cree tareas, analice proyectos, ayude a gestionar prioridades y más.

Este servidor aprovecha la librería Things.py y el Things URL Scheme.

Apoya el Proyecto

Si encuentras útil este proyecto, considera apoyar su desarrollo:

Características

Acceso a todas las listas principales de Things (Bandeja de entrada, Hoy, Próximos, etc.)
Gestión de proyectos y áreas
Operaciones con etiquetas
Capacidades de búsqueda avanzada
Elementos recientes
Información detallada de elementos, incluyendo listas de verificación
Soporte para datos anidados (proyectos dentro de áreas, tareas dentro de proyectos)
Filtrado de proyectos de Someday: las tareas en proyectos de Someday se excluyen automáticamente de las vistas Hoy, Próximos y Cualquier momento, coincidiendo con el comportamiento de la interfaz de Things

Instalación

Requisitos previos

macOS (Things 3 es solo para Mac)
Aplicación Things 3 con "Habilitar URLs de Things" activado (Configuración → General)
Un cliente MCP, como Claude Desktop o Claude Code
uv gestor de paquetes de Python: brew install uv

Instalar vía uvx (Cualquier cliente MCP)

Things MCP está publicado en PyPI y se puede ejecutar directamente con uvx:

uvx things-mcp

Configura tu cliente MCP para usar uvx con things-mcp como argumento.

Claude Desktop

Opción 1: Instalación con un clic (Recomendada)

Descarga el archivo más reciente desde la página de versiones
Haz doble clic en el archivo .mcpb
¡Listo!

Opción 2: Configuración manual

Ve a Claude → Configuración → Desarrollador → Editar configuración
Añade el servidor de Things:

{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": ["things-mcp"]
    }
  }
}

Guarda y reinicia Claude Desktop

Claude Code

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

Para hacerlo disponible globalmente (en todos los proyectos), añade -s user:

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

Verificar que funciona

Después de la instalación:

Si usas Claude Desktop, deberías ver "Things MCP" en la lista de "Buscar y herramientas"
Intenta preguntar: "¿Qué hay en mi bandeja de entrada de Things?"

Ejemplos de uso con Claude Desktop

"¿Qué hay en mi lista de tareas de hoy?"
"Crea una tarea para empacar para mis vacaciones en la playa la próxima semana, incluye una lista de verificación de empaque."
"Evalúa mis tareas actuales usando la matriz de Eisenhower."
"Ayúdame a realizar una revisión semanal estilo GTD usando Things."
"Muéstrame tareas que no se han modificado en más de un mes."

Consejos

Crea un proyecto en Claude con instrucciones personalizadas que expliquen cómo usas Things y organizas áreas, proyectos, etiquetas, etc. Dile a Claude qué información quieres que incluya cuando cree una nueva tarea (por ejemplo, pedirle que incluya detalles relevantes en la descripción de la tarea podría ser útil).
Intenta añadir otro servidor MCP que le dé a Claude acceso a tu calendario. Esto te permitirá pedirle a Claude que reserve tiempo en tu calendario para tareas específicas, crear tareas pendientes a partir de eventos próximos del calendario (por ejemplo, preparación para una reunión), etc.
Usa la antigüedad de las tareas para identificar elementos obsoletos: "¿Qué tareas en mi lista de Cualquier momento tienen más de 2 semanas?"

Herramientas disponibles

Vistas de lista

get-inbox - Obtener tareas de la bandeja de entrada
get-today - Obtener tareas con vencimiento hoy
get-upcoming - Obtener tareas próximas
get-anytime - Obtener tareas de la lista Cualquier momento
get-someday - Obtener tareas de la lista Someday, incluyendo tareas en proyectos de Someday
get-logbook - Obtener tareas completadas
get-trash - Obtener tareas en la papelera

Operaciones básicas

get-todos - Obtener tareas, opcionalmente filtradas por proyecto
get-projects - Obtener todos los proyectos
get-areas - Obtener todas las áreas

Operaciones con etiquetas

get-tags - Obtener todas las etiquetas
get-tagged-items - Obtener elementos con una etiqueta específica
get-tag-usage - Informar cuántos elementos usan cada etiqueta, ordenados por uso; marcar etiquetas no utilizadas para limpieza

Operaciones de búsqueda

search-todos - Búsqueda simple por título/notas
search-advanced - Búsqueda avanzada con múltiples filtros

Operaciones basadas en tiempo

get-recent - Obtener elementos creados recientemente

Operaciones del Things URL Scheme

add-todo - Crear una nueva tarea
add-project - Crear un nuevo proyecto
add-area - Crear una nueva área (vía AppleScript; el Things URL scheme no tiene comando para añadir áreas)
update-area - Actualizar un área existente: renombrar o establecer etiquetas (vía AppleScript)
update-todo - Actualizar una tarea existente
bulk-update-todos - Aplicar la misma actualización a muchas tareas en una sola operación
update-project - Actualizar un proyecto existente
show-item - Mostrar un elemento o lista específica en Things
search-items - Buscar elementos en Things

Parámetros de herramientas

Paginación (la mayoría de las herramientas de lectura)

Las herramientas de lectura de listas/búsqueda (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) aceptan paginación opcional:

limit - Número máximo de elementos a devolver (predeterminado: todos; get-logbook tiene como predeterminado 50)
offset - Número de elementos a omitir desde el inicio (predeterminado: 0)

Cuando no se establece ninguno, la salida no cambia. Cuando se establece, se antepone un encabezado Showing X-Y of Z items para que sepas cuánto más hay. Un offset más allá del final se informa de manera distinta a un resultado vacío.

Estas mismas herramientas de lectura también devuelven contenido estructurado junto con el texto legible para humanos: los clientes MCP reciben los diccionarios de elementos sin procesar más count/total/offset/limit bajo structured_content, para que los datos puedan consumirse programáticamente sin analizar el texto formateado.

get-todos

project_uuid (opcional) - Filtrar tareas por proyecto
include_items (opcional, predeterminado: true) - Incluir elementos de listas de verificación

get-projects / get-areas / get-tags

include_items (opcional, predeterminado: false) - Incluir elementos contenidos

search-advanced

status - Filtrar por estado (incompleto/completado/cancelado)
start_date - Filtrar por fecha de inicio (AAAA-MM-DD)
deadline - Filtrar por fecha límite (AAAA-MM-DD)
tag - Filtrar por etiqueta
area - Filtrar por UUID de área
type - Filtrar por tipo de elemento (tarea/proyecto/encabezado)
last - Filtrar por fecha de creación (por ejemplo, '3d' para los últimos 3 días, '1w' para la última semana)

get-recent

period - Período de tiempo (por ejemplo, '3d', '1w', '2m', '1y')

get-logbook

period (opcional, predeterminado: '7d') - Ventana de retroceso por fecha de finalización. Acepta d/w/m/y (por ejemplo, '3d', '1w', '2m', '1y'); meses ≈ 30 días, años ≈ 365 días
limit (opcional, predeterminado: 50) - Número máximo de elementos completados a devolver

get-tag-usage

only_unused (opcional, predeterminado: false) - Devolver solo etiquetas que ningún elemento referencia (candidatas a limpieza)

update-todo (lista de verificación y etiquetas)

tags - Reemplazar todas las etiquetas de la tarea
add_tags - Añadir etiquetas sin eliminar las existentes
checklist_items - Reemplazar toda la lista de verificación con esta lista
prepend_checklist_items - Añadir estos elementos al inicio de la lista de verificación
append_checklist_items - Añadir estos elementos al final de la lista de verificación

bulk-update-todos

Aplica el mismo cambio a cada tarea en ids en una sola operación. Requiere que el token de autenticación de Things esté habilitado (Things → Configuración → General → Habilitar URLs de Things → Gestionar); el servidor lo lee automáticamente.

ids (obligatorio) - Lista de UUIDs de tareas a actualizar
list / list_id - Mover todas a un proyecto/área (por título o UUID)
tags / add_tags - Reemplazar o añadir etiquetas en todas
when - Reprogramar todas (palabra clave o AAAA-MM-DD)
deadline - Establecer fecha límite en todas (AAAA-MM-DD)
heading / heading_id - Mover todas bajo un encabezado (por título o UUID)
completed / canceled - Marcar todas como completadas o canceladas

Programación con recordatorios (add-todo, add-project, update-todo, update-project)

when - Acepta múltiples formatos:
- Palabras clave: today, tomorrow, evening, anytime, someday
- Fecha: YYYY-MM-DD (por ejemplo, 2024-01-15)
- Fecha y hora con recordatorio: YYYY-MM-DD@HH:MM (por ejemplo, 2024-01-15@14:30)

Solución de problemas

Si no funciona:

Asegúrate de que Things 3 esté instalado y se haya abierto al menos una vez
- La base de datos de Things debe existir para que el servidor funcione
Comprueba que "Habilitar URLs de Things" esté activado
- Abre Things → Configuración → General → Habilitar URLs de Things
Claude Desktop no puede encontrar uvx
- Instala uv globalmente con Homebrew (brew install uv)
- Alternativa: Usa la ruta completa a uvx en tu configuración. Encuéntrala con which uvx (normalmente /Users/USERNAME/.local/bin/uvx)

Desarrollo

Ejecutar pruebas

El proyecto incluye un conjunto completo de pruebas unitarias para los módulos de URL scheme y formateador.

# 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"

Prueba de integración MCP

El proyecto incluye un plan de pruebas de integración que puede ejecutarse mediante Claude (vía Claude Cowork o Claude Code) para verificar que todas las herramientas MCP funcionan correctamente contra una base de datos de Things en vivo.

Consulta docs/mcp_integration_test_plan.md para el plan de pruebas completo.

Estructura del proyecto

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 defecto, el servidor usa transporte stdio para la comunicación con clientes MCP. Para escenarios de acceso remoto, puedes ejecutar el servidor con transporte HTTP.

Configuración

Establece estas variables de entorno para habilitar el transporte HTTP:

Variable	Predeterminado	Descripción
`THINGS_MCP_TRANSPORT`	`stdio`	Tipo de transporte: `stdio` o `http`
`THINGS_MCP_HOST`	`127.0.0.1`	Dirección de enlace del servidor HTTP
`THINGS_MCP_PORT`	`8000`	Puerto del servidor HTTP

Ejemplo

# 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

Consulta .env.example para un archivo de configuración de muestra.