Servidor MCP de OmniFocus

Un servidor de Protocolo de Contexto de Modelo (MCP) que conecta OmniFocus con Claude y otros asistentes de IA compatibles con MCP.

Resumen

Este servidor une a los asistentes de IA con tu base de datos de OmniFocus. Mediante conversación natural, un asistente puede consultar, crear, editar y eliminar tareas y proyectos, incluidas operaciones masivas. Algunas cosas que puedes hacer con él:

• Convertir un PDF de un programa de estudios en un proyecto completamente especificado con tareas, etiquetas, fechas de aplazamiento y fechas de vencimiento

• Convertir la transcripción de una reunión en una lista de acciones

• Auditar y reorganizar tus etiquetas, proyectos y carpetas de forma conversacional

• Crear visualizaciones de tus tareas, proyectos y etiquetas

• Procesar docenas de elementos en una sola operación por lotes

Related MCP server: MCP OmniFocus

Inicio rápido

Requisitos previos

• macOS con OmniFocus instalado

• Node.js 20 o posterior (para npx)

La primera vez que el servidor hable con OmniFocus, macOS te pedirá que permitas el acceso de automatización. Concédelo una vez y listo.

Claude Desktop

Añade el servidor a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "npx",
      "args": ["-y", "omnifocus-mcp"]
    }
  }
}

Luego reinicia Claude Desktop.

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp

Otros clientes MCP funcionan de la misma manera: ejecuta npx -y omnifocus-mcp a través de stdio.

Ejemplos de conversación

Consultas específicas:

"Muéstrame todas mis tareas marcadas con bandera que vencen esta semana"

"¿Cuáles son mis próximas acciones en la carpeta Trabajo?"

"Cuenta cuántas tareas hay en cada proyecto"

Reorganización:

"Quiero que cada tarea tenga una etiqueta de nivel de energía. Muéstrame una lista de todas las tareas que no tienen una y tus sugerencias sobre qué etiqueta añadir. Haré los cambios que considere apropiados. Luego haz los cambios en OmniFocus."

Captura desde cualquier lugar:

"Vale, gracias por la explicación detallada de por qué el estado de derecho es importante. Añade una tarea recurrente a mi proyecto de activismo que me recuerde llamar a mi representante semanalmente. Incluye un resumen de esta conversación en el campo de notas."

Trabajar con perspectivas:

"¿Qué perspectivas tengo disponibles?"

"Muéstrame lo que hay en mi perspectiva Bandeja de entrada"

Procesar transcripciones o PDFs:

"Voy a pegar la transcripción de la reunión de hoy. Por favor, analízala y crea tareas en OmniFocus para cualquier elemento de acción asignado a mí. Ponlas en mi proyecto 'Desarrollo de Producto'."

Herramientas

El servidor proporciona 12 herramientas. Los parámetros opcionales están marcados.

query_omnifocus

Consulta tareas, proyectos o carpetas con filtros específicos: mucho más rápido y ligero que volcar toda la base de datos. Consulta QUERY_TOOL_REFERENCE.md para la referencia completa y QUERY_TOOL_EXAMPLES.md para ejemplos prácticos.

Filtros disponibles:

• Contenedores: projectName (coincidencia parcial sin distinción de mayúsculas; "inbox" apunta a la bandeja de entrada), projectId, folderId (incluye subcarpetas), folderName (coincidencia parcial sin distinción de mayúsculas, incluye subcarpetas)

• Nombres: taskName (coincidencia parcial sin distinción de mayúsculas)

• Etiquetas: tags (coincidencia exacta, distingue mayúsculas)

• Estado: status — tareas: Next, Available, Blocked, DueSoon, Overdue, Completed, Dropped; proyectos: Active, OnHold, Done, Dropped

• Fechas, orientadas al futuro: dueWithin, deferredUntil, plannedWithin (rangos), dueOn, deferOn, plannedOn (día exacto). Acepta un número de días, "today", "tomorrow", "this week", "next week" o una fecha ISO

• Fechas, orientadas al pasado: addedWithin, addedOn, completedWithin, completedOn, droppedWithin, droppedOn (los filtros de completado/descartado requieren includeCompleted: true)

• Marcas y varios: flagged, inbox, hasNote, isRepeating, reviewDue (solo proyectos)

dump_database

Obtén el estado completo de tu base de datos. Úsalo para análisis exhaustivos; prefiere query_omnifocus para cualquier consulta específica.

• hideCompleted (opcional): oculta tareas completadas/descartadas (por defecto: true)

• hideRecurringDuplicates (opcional): oculta instancias duplicadas de tareas recurrentes (por defecto: true)

add_omnifocus_task

Crea una nueva tarea.

• name

• projectName (opcional): proyecto al que añadir la tarea (por defecto: bandeja de entrada)

• parentTaskId / parentTaskName (opcional): anidar bajo una tarea existente

• note, dueDate, deferDate, plannedDate, flagged, estimatedMinutes, tags (todos opcionales)

• repeat (opcional): hacerla recurrente — consulta Elementos recurrentes

add_project

Crea un nuevo proyecto.

• name

• folderName (opcional): carpeta donde colocar el proyecto

• sequential (opcional): si las tareas deben completarse en orden

• note, dueDate, deferDate, flagged, estimatedMinutes, tags, repeat (todos opcionales)

edit_item

Edita una tarea o proyecto existente. También es la forma de mover elementos: establece newProjectName para mover una tarea a un proyecto, o ""/"inbox" para enviarla a la bandeja de entrada.

• id o name: qué elemento editar (el id tiene prioridad)

• itemType: task o project

• Comunes: newName, newNote, newDueDate, newDeferDate, newFlagged, newEstimatedMinutes (fechas en formato ISO; cadena vacía borra)

• Tareas: newStatus (incomplete, completed, dropped, skipped — skipped solo para tareas recurrentes), addTags, removeTags, replaceTags, newProjectName, newPlannedDate

• Proyectos: newProjectStatus (active, completed, dropped, onHold), newFolderName, newSequential, markReviewed (establece la próxima fecha de revisión según el intervalo de revisión del proyecto)

• Repetición: newRepeat establece una nueva regla (misma forma que repeat al crear); newRepeat: null la borra

remove_item

Elimina una tarea o proyecto.

• id o name: qué elemento eliminar

• itemType: task o project

batch_add_items

Crea múltiples tareas y proyectos en una sola operación. Cada elemento acepta los mismos campos que add_omnifocus_task / add_project, más type (task o project) y ayudantes de jerarquía opcionales:

• tempId: un ID temporal al que otros elementos del mismo lote pueden hacer referencia

• parentTempId: anida este elemento bajo el tempId de otro elemento del lote

{
  "items": [
    { "type": "project", "name": "My Project", "tempId": "proj1" },
    { "type": "task", "name": "First task", "parentTempId": "proj1" },
    { "type": "task", "name": "Parent task", "parentTempId": "proj1", "tempId": "t1" },
    { "type": "task", "name": "Subtask", "parentTempId": "t1" }
  ]
}

batch_remove_items

Elimina múltiples tareas o proyectos en una sola operación. Cada elemento toma id o name, más itemType.

list_perspectives

Lista las perspectivas disponibles, tanto integradas como personalizadas (las perspectivas personalizadas son una función de OmniFocus Pro).

• includeBuiltIn, includeCustom (opcional, por defecto: true)

get_perspective_view

Obtén los elementos visibles en una perspectiva con nombre.

• perspectiveName: p. ej., Inbox, Flagged o un nombre de perspectiva personalizada

• limit (opcional, por defecto: 100), includeMetadata (opcional), fields (opcional)

list_tags

Lista todas las etiquetas con su jerarquía, estado activo y recuentos de tareas.

• includeDropped (opcional, por defecto: false)

create_tag

Crea una etiqueta, opcionalmente anidada bajo una etiqueta principal existente.

• name

• parentTagName / parentTagID (opcional; el ID tiene prioridad)

Elementos recurrentes

add_omnifocus_task, add_project y cada elemento en batch_add_items aceptan un objeto repeat; edit_item acepta newRepeat. Describes el horario y el servidor compila la regla de recurrencia ICS, por lo que nunca escribes una RRULE a mano.

{ "name": "Weekly review", "repeat": { "method": "start-after-completion", "unit": "week" } }
{ "name": "Strength work", "repeat": { "method": "fixed", "unit": "week", "weekdays": ["TU","TH"] } }

Elige method deliberadamente — es el campo que más a menudo se configura mal a mano. Con fixed, las ocurrencias aparecen según el horario tanto si la última se completó como si no, por lo que una semana perdida deja un atraso que ponerse al día. Con start-after-completion, la próxima ocurrencia se programa desde el momento en que realmente la completas, por lo que el hábito simplemente se reanuda.

Lee una regla de vuelta con query_omnifocus usando los campos repetitionRule (cadena ICS) y repetitionMethod, o filtra con isRepeating.

Actualmente no se admiten: reglas mensuales posicionales ("tercer martes"), días específicos del mes y condiciones de fin (COUNT/UNTIL). Configúralos directamente en OmniFocus.

Recursos

Los recursos permiten a los clientes MCP adjuntar datos de OmniFocus a una conversación como contexto, sin llamadas a herramientas. En Claude Code, escribe @ para explorarlos; Claude Desktop y otros clientes que admiten recursos pueden adjuntarlos directamente. Todos los recursos devuelven JSON.

Los dos recursos de plantilla admiten listar todos los valores disponibles y autocompletar el parámetro {name}.

Instrucciones del servidor y registro

Instrucciones: durante el apretón de manos MCP, el servidor envía orientación de uso al cliente: consejos de selección de herramientas (prefiere query_omnifocus sobre dump_database), consejos de filtros y el catálogo de recursos. No se necesita configuración.

Registro: el servidor emite registros estructurados a través del protocolo de registro MCP. Los clientes pueden ajustar la verbosidad con logging/setLevel (debug, info, warning, error, ...). El tiempo de ejecución de los scripts y los errores se registran automáticamente.

Cómo funciona

El servidor se comunica con OmniFocus a través de osascript, usando JXA (JavaScript for Automation) y la automatización Omni integrada de OmniFocus (OmniJS) cuando corresponde. Está construido sobre el MCP TypeScript SDK oficial y se comunica con los clientes a través de stdio.

Demonio compartido

Al lanzar omnifocus-mcp se inicia un pequeño shim que se conecta a un demonio de fondo compartido, iniciando uno si aún no está en ejecución. Cada cliente en la máquina obtiene su propia sesión MCP independiente, pero todos se ejecutan dentro de ese único proceso.

Esto importa cuando varios agentes usan OmniFocus a la vez. OmniFocus es una aplicación de un solo hilo controlada mediante AppleEvents, y el servidor limita cuántas llamadas osascript ejecutará de forma concurrente. Cuando cada cliente ejecutaba su propio servidor, ese límite era por proceso: diez clientes significaban diez presupuestos independientes apuntando a una sola aplicación, lo que provocaba tiempos de espera de AppleEvent. Compartir un solo proceso hace que el límite sea global.

El demonio escucha en un socket de dominio Unix en un directorio 0700 (~/.omnifocus-mcp/daemon-<version>.sock por defecto), por lo que el acceso está controlado por el sistema de archivos: sin puerto de red y sin token. Se cierra solo cuando ningún cliente ha estado conectado durante el período de inactividad, y registra en daemon.log junto al socket.

El nombre del socket incluye la versión del paquete para que una actualización nunca te deje hablando con el demonio de la versión anterior. Justo después de una actualización, es posible que veas brevemente dos demonios: el antiguo sigue sirviendo a los clientes ya conectados a él y se cierra cuando el último de ellos se desconecta. Los clientes que aún están conectados al demonio antiguo reciben un aviso en banda: mientras un demonio más nuevo está sirviendo, cada resultado de herramienta incluye un aviso de actualización de una línea, para que nadie tenga que recordar reconectarse.

Nada cambia en la configuración del cliente. Si el demonio no se puede iniciar (un sandbox inusual, un directorio de inicio de solo lectura), el shim recurre a ejecutar un servidor independiente en el proceso, exactamente como lo hacían las versiones anteriores.

Variables de entorno

Hoja de ruta

• Soporte de prompt de MCP

• Manipulación de notificaciones para proyectos y tareas

• Consulte los problemas de GitHub para solicitudes de funciones y problemas conocidos

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una solicitud de extracción. CI ejecuta verificación de tipos, pruebas unitarias y una compilación en cada PR.

npm install
npm test            # unit tests
npm run build       # compile to dist/
npm run test:integration  # requires OmniFocus; creates and removes TEST:-prefixed items

Licencia

MIT