omnifocus-mcp

Un servidor MCP para OmniFocus que expone toda la API de JavaScript de Omni Automation a los clientes de LLM.

Solo macOS. Requiere que OmniFocus se esté ejecutando en la misma máquina. Toda la implementación ejecuta fragmentos OmniJS dentro de OmniFocus mediante osascript -l JavaScript — sin generación de cadenas de AppleScript ni limitaciones del diccionario de scripting.

Requisitos previos

• macOS (Omni Automation solo está disponible en macOS; el servidor no se iniciará en otras plataformas)

• OmniFocus instalado y en ejecución

• Node.js ≥ 20

Related MCP server: OmniFocus MCP Server

Instalación

El paquete se publica en npm como @scardis/omnifocus-mcp.

Mediante npx (sin necesidad de instalar)

Añádelo a la configuración de tu cliente MCP (p. ej., Claude Desktop claude_desktop_config.json):

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

Desde el código fuente

git clone https://github.com/steveardis/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

Luego configura tu cliente MCP:

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/absolute/path/to/omnifocus-mcp/dist/server.js"]
    }
  }
}

Herramientas disponibles

Lectura

Escritura

Modelo de direccionamiento

Cada entidad devuelta por este servidor incluye un campo id estable (id.primaryKey de OmniFocus). Usa este ID en las llamadas posteriores en lugar de los nombres. Los nombres pueden ser ambiguos; los IDs no.

Si tienes un nombre pero no un ID, usa resolve_name. Devuelve una lista — si se devuelven varios candidatos, inspecciona el campo path y pide al usuario que desambigüe antes de continuar con cualquier operación de escritura.

Comparación con otros servidores MCP de OmniFocus

Existen dos alternativas destacables: themotionmachine/OmniFocus-MCP y jqlts1/omnifocus-mcp-enhanced (un fork de la anterior con herramientas adicionales).

API de scripting. Las alternativas usan el diccionario de scripting de JXA o AppleScript para controlar OmniFocus. Este servidor realiza una única llamada JXA — Application('OmniFocus').evaluateJavascript() — y ejecuta toda la lógica como OmniJS (Omni Automation) dentro de OmniFocus. Esto da acceso a toda la superficie de la API de Omni Automation (reglas de recurrencia, intervalos de revisión, perspectivas, forecast, archivos adjuntos, automatización de URLs, etc.) en lugar del más limitado diccionario de scripting.

Inyección de argumentos. Las alternativas construyen comandos de osascript mediante interpolación de cadenas, lo que puede fallar con apóstrofos, comillas, barras invertidas y caracteres Unicode en los nombres. Este servidor serializa todos los argumentos con JSON.stringify en un literal de JS.

Direccionamiento de entidades. Las alternativas direccionan las entidades principalmente por nombre. Este servidor devuelve un id estable (id.primaryKey) para cada entidad y proporciona resolve_name para asignar un nombre a candidatos de ID — devolviendo todas las coincidencias con rutas completas en lugar de elegir una silenciosamente cuando los nombres son ambiguos.

CRUD completo. Este servidor permite crear, editar, completar, descartar, eliminar y mover tareas, proyectos, carpetas y etiquetas, además de reglas de repetición y la fecha planned de OmniFocus 4.

Desarrollo

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

Pruebas

Pruebas unitarias (no requieren OmniFocus)

npm test

Pruebas de integración

⚠️ Las pruebas de integración se ejecutan contra tu base de datos real de OmniFocus.

Cada ejecución de pruebas crea una carpeta temporal de nivel superior llamada __MCP_TEST_<uuid>__ y la elimina al finalizar. Si una ejecución se interrumpe antes de la finalización, ejecuta el script de limpieza:

npm run test:cleanup-fixtures

⚠️ Advertencia sobre la sincronización: De forma predeterminada, las pruebas de integración se niegan a ejecutarse si la sincronización de OmniFocus está activada, para evitar que los datos de prueba se propaguen a tus otros dispositivos. Desactiva primero la sincronización de OmniFocus o establece MCP_TEST_ALLOW_SYNC=1 para optar por participar (los datos de prueba se sincronizarán):

# Default (refuses if sync enabled)
npm run test:integration

# With sync enabled (use carefully)
MCP_TEST_ALLOW_SYNC=1 npm run test:integration

Limpiar datos de prueba obsoletos

npm run test:cleanup-fixtures

Esto elimina cualquier carpeta __MCP_TEST_*__ y los proyectos/etiquetas __mcp_*__ huérfanos que hayan quedado en OmniFocus tras ejecuciones de pruebas interrumpidas.

Contribuciones

¡Las contribuciones son bienvenidas! A continuación te explicamos cómo empezar:

1. Haz un fork y clona el repositorio

2. Instala las dependencias: npm install

3. Ejecuta las pruebas unitarias (no se necesita OmniFocus): npm test

4. Ejecuta las pruebas de integración (requiere macOS + OmniFocus): npm run test:integration

Antes de enviar un PR

• npm run typecheck — debe pasar sin errores

• npm test — todas las pruebas unitarias deben pasar

• npm run test:integration — todas las pruebas de integración deben pasar (solo macOS)

• Mantén los cambios enfocados: una funcionalidad o corrección por PR

Descripción general de la arquitectura

El servidor ejecuta fragmentos OmniJS dentro de OmniFocus mediante osascript -l JavaScript. Cada herramienta tiene tres capas:

• Esquema (src/schemas/shapes.ts) — esquemas Zod para la validación de entrada y el análisis de salida.

• Fragmento (`src/snippets/*.