Servidor MCP de Things

Este servidor de Protocolo de Contexto de Modelo (MCP) te permite usar Claude Desktop para interactuar con tus datos de gestión de tareas en la app Things . Puedes pedirle a Claude que cree tareas, analice proyectos, te ayude a gestionar prioridades y mucho más.

Este servidor aprovecha la biblioteca Things.py y el esquema de URL de Things .

¿Por qué Things MCP?

Este servidor MCP libera el poder de la IA para la gestión de tareas:

• Creación de tareas en lenguaje natural : pídale a Claude que cree tareas con todos los detalles en lenguaje natural
• Análisis de tareas inteligentes : obtenga información sobre sus proyectos y patrones de productividad
• GTD y flujos de trabajo de productividad : deje que Claude le ayude a implementar sistemas de productividad
• Integración perfecta : funciona directamente con sus datos existentes de Things 3

Características

• Acceso a todas las listas principales de cosas (Bandeja de entrada, Hoy, Próximos, etc.)
• Gestión de proyectos y áreas
• Operaciones de etiquetas
• Capacidades de búsqueda avanzada
• Seguimiento de artículos recientes
• Información detallada del artículo, incluidas listas de verificación
• Soporte para datos anidados (proyectos dentro de áreas, tareas pendientes dentro de proyectos)

Opciones de instalación

Hay varias formas de instalar y utilizar el servidor Things MCP:

Opción 1: Instalar desde PyPI (recomendado)

Prerrequisitos

• Python 3.12+
• Escritorio de Claude
• Cosas 3 ("Habilitar URL de Cosas" debe estar activado en Configuración -> General)

Instalación

O usando uv (recomendado):

Correr

Después de la instalación, puede ejecutar el servidor directamente:

Opción 2: Instalación manual

Prerrequisitos

• Python 3.12+
• Escritorio de Claude
• Cosas 3 ("Habilitar URL de Cosas" debe estar activado en Configuración -> General)

Paso 1: Instalar uv

Instale uv si aún no lo ha hecho:

Luego reinicia tu terminal.

Paso 2: Clonar este repositorio

Paso 3: Configurar el entorno y las dependencias de Python

Paso 4: Configurar el token de autenticación de Things

Ejecute la herramienta de configuración para configurar su token de autenticación de Things:

Esto lo guiará a través del proceso de configuración de su token de autenticación de Things, que es necesario para que el servidor MCP interactúe con su aplicación Things.

Paso 5: Configurar Claude Desktop

Editar el archivo de configuración de Claude Desktop:

Agregue el servidor Things a la clave mcpServers en el archivo de configuración (asegúrese de actualizar la ruta a la carpeta donde instaló estos archivos):

Paso 6: Reiniciar Claude Desktop

Reinicie la aplicación Claude Desktop para aplicar los cambios.

Ejemplo de uso con Claude Desktop

• "¿Qué hay en mi lista de tareas para hoy?"
• "Crea una lista de cosas por hacer para preparar el equipaje para mis vacaciones en la playa la próxima semana. Incluye una lista de verificación para empacar".
• "Evalúa mis tareas actuales utilizando la matriz de Eisenhower".
• "Ayúdame a realizar una revisión semanal al estilo GTD usando Things".

Consejos

• Crea un proyecto en Claude con instrucciones personalizadas que expliquen cómo usar Things y organizar áreas, proyectos, etiquetas, etc. Dile a Claude qué información quieres que se 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 agregar otro servidor MCP que le dé a Claude acceso a tu calendario. Esto te permitirá pedirle que bloquee tiempo en tu calendario para tareas específicas, cree tareas a partir de próximos eventos del calendario (por ejemplo, prepararse para una reunión), etc.

Herramientas disponibles

Vistas de lista

• get-inbox - Obtener todos los archivos de la Bandeja de entrada
• get-today - Obtener las tareas pendientes que vencen hoy
• get-upcoming - Obtén tus próximas tareas pendientes
• get-anytime - Obtener tareas pendientes de la lista Anytime
• get-someday - Obtener tareas pendientes de la lista Someday
• get-logbook - Obtener tareas completadas
• get-trash - Obtener todos los archivos eliminados

Operaciones básicas

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

Operaciones de etiquetas

• get-tags - Obtener todas las etiquetas
• get-tagged-items - Obtener elementos con una etiqueta específica

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 el tiempo

• get-recent - Obtener elementos creados recientemente

Parámetros de la herramienta

tareas pendientes

• project_uuid (opcional) - Filtrar tareas por proyecto
• include_items (opcional, valor predeterminado: verdadero): incluye elementos de la lista de verificación

obtener-proyectos / obtener-áreas / obtener-etiquetas

• include_items (opcional, predeterminado: falso): incluye elementos contenidos

búsqueda avanzada

• 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 (tareas pendientes/proyecto/encabezado)

obtener reciente

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

añadir tareas pendientes

• title - Título de la tarea
• notes (opcional) - Notas para la tarea pendiente
• when (opcional) - Cuándo programar la tarea (hoy, mañana, por la tarde, en cualquier momento, algún día o AAAA-MM-DD)
• deadline (opcional) - Fecha límite para la tarea (AAAA-MM-DD)
• tags (opcional) - Etiquetas para aplicar a la tarea pendiente
• list_title o list_id (opcional): título o ID del proyecto/área a agregar
• heading (opcional) - Encabezado para agregar debajo
• checklist_items (opcional) - Elementos de la lista de verificación para agregar

actualizar-todo

• id - ID de la tarea a actualizar
• title (opcional) - Nuevo título
• notes (opcional) - Nuevas notas
• when (opcional) - Nuevo horario
• deadline (opcional) - Nueva fecha límite
• tags (opcional) - Nuevas etiquetas
• completed (opcional) - Marcar como completado
• canceled (opcional) - Marcar como cancelado

añadir proyecto

• title - Título del proyecto
• notes (opcional) - Notas para el proyecto
• when (opcional) - Cuándo programar el proyecto
• deadline (opcional) - Fecha límite para el proyecto
• tags (opcional) - Etiquetas para aplicar al proyecto
• area_title o area_id (opcional) - Título o ID del área a agregar
• todos (opcional) - Todos iniciales para crear en el proyecto

actualizar-proyecto

• id - ID del proyecto a actualizar
• title (opcional) - Nuevo título
• notes (opcional) - Nuevas notas
• when (opcional) - Nuevo horario
• deadline (opcional) - Nueva fecha límite
• tags (opcional) - Nuevas etiquetas
• completed (opcional) - Marcar como completado
• canceled (opcional) - Marcar como cancelado

elemento de exhibición

• id - ID del elemento a mostrar, o uno de los siguientes: bandeja de entrada, hoy, próximo, en cualquier momento, algún día, libro de registro
• query (opcional) - Consulta opcional para filtrar por
• filter_tags (opcional) - Etiquetas opcionales para filtrar

Configuración del token de autenticación

El servidor MCP de Things requiere un token de autenticación para interactuar con la aplicación Things. Este token se utiliza para autorizar los comandos del esquema de URL.

Cómo obtener tu token de autenticación de Things

1. Abre la aplicación Things en tu Mac
2. Vaya a Cosas → Preferencias (⌘,)
3. Seleccione la pestaña General
4. Asegúrate de que la opción "Habilitar URL de cosas" esté marcada
5. Busque el token de autenticación que se muestra en la ventana de preferencias

Configurando el token

Ejecute la herramienta de configuración incluida para configurar su token:

Este script interactivo le solicitará su token y lo guardará de forma segura en su configuración local.

Desarrollo

Este proyecto utiliza pyproject.toml para gestionar las dependencias y la configuración de compilación. Se creó con el Protocolo de Contexto de Modelo , que permite a Claude acceder de forma segura a herramientas y datos.

Opciones de implementación

Este proyecto ofrece dos enfoques de implementación diferentes:

1. Servidor MCP estándar ( things_server.py ): la implementación original que utiliza el patrón básico de servidor MCP.
2. Servidor FastMCP ( things_fast_server.py ): una implementación moderna que utiliza el patrón FastMCP para un código más limpio y fácil de mantener con registro de herramientas basado en decoradores.

Flujo de trabajo de desarrollo

Configuración de un entorno de desarrollo

Probar cambios durante el desarrollo

Utilice el servidor de desarrollo MCP para probar los cambios:

Construyendo el paquete para PyPI

Publicación en PyPI

Requiere Python 3.12+.

Solución de problemas

El servidor incluye gestión de errores para:

• UUID no válidos
• Faltan parámetros requeridos
• Errores de acceso a la base de datos de Things
• Errores de formato de datos
• Problemas con el token de autenticación

Problemas comunes

1. Token faltante o no válido : ejecute python configure_token.py para configurar su token
2. La aplicación Things no se ejecuta : asegúrese de que Things 3 esté abierto al usar el servidor MCP
3. Esquema de URL no habilitado : Verifique que la opción "Habilitar URL de Things" esté habilitada en Things → Preferencias → General

Comprobación de registros

Todos los errores se registran y se devuelven con mensajes descriptivos. Para revisar los registros de MCP desde Claude Desktop, ejecute lo siguiente en la terminal: