Servidor MCP

Mindwtr ofrece un servidor opcional de MCP (Model Context Protocol). Esto te permite conectar agentes de IA (como Claude Desktop, Claude Code, OpenAI Codex o Gemini CLI) a tu base de datos local de Mindwtr, a la API local de escritorio o a un endpoint autoalojado de Mindwtr Cloud.

El asistente independiente usa stdio de forma predeterminada.

Referencia de implementación: apps/mcp-server/README.md. Si ese README difiere del código actual del servidor o de los esquemas generados de las herramientas MCP, prevalecen el código y los esquemas.

Binarios de la aplicación frente al asistente MCP

El asistente MCP independiente sigue disponible como mindwtr-mcp y figura en el Registro MCP público.

No necesitas ejecutar toda la aplicación desde el código fuente para usar MCP. Usa el binario normal de la aplicación de escritorio para tus tareas y deja que tu cliente MCP inicie mindwtr-mcp con npx, o instálalo globalmente con npm. Haz que el asistente apunte al archivo mindwtr.db local de la aplicación de escritorio, o usa el backend de API local que se describe a continuación.

En escritorio, las rutas predeterminadas de la base de datos aparecen más abajo, en Ubicaciones predeterminadas de la base de datos. Los binarios móviles no exponen un servidor MCP local.

MCP integrado en escritorio

La aplicación de escritorio incluye un servidor MCP en Ajustes → Integraciones → Servidor MCP local (avanzado). Se ejecuta dentro de la aplicación y comparte las operaciones internas con la API local. No se necesita Node, npm, Bun ni un asistente independiente, y el interruptor de la API local puede permanecer desactivado. MCP está desactivado y es de solo lectura de forma predeterminada.

Activa el servidor y mantén Mindwtr abierto. Cerrar a la bandeja lo mantiene disponible; desactivar MCP o salir de la aplicación lo detiene. Los clientes deben admitir Streamable HTTP autenticado. El endpoint predeterminado es:

text

http://127.0.0.1:8722/mcp

Disponible a partir de v1.3.7: los controles siguientes añaden la copia de la configuración de Codex, un puerto configurable y permisos de escritura separados. Las versiones anteriores usan un puerto fijo y un único interruptor Permitir cambios.

Conectar Codex

Selecciona Copiar para Codex y añade el TOML copiado a ~/.codex/config.toml. Si ese archivo ya contiene mcp_servers.mindwtr, reemplaza esa entrada en lugar de añadir una duplicada. Conserva el resto de tu configuración. Mindwtr copia el texto; no edita los archivos de Codex.

La configuración copiada tiene esta estructura, con tu endpoint y token actuales:

toml

[mcp_servers.mindwtr]
url = "http://127.0.0.1:8722/mcp"

[mcp_servers.mindwtr.http_headers]
Authorization = "Bearer <token from Mindwtr>"

Reinicia o vuelve a conectar tu cliente Codex después de cambiar su configuración. Copiar datos de conexión proporciona JSON para los clientes que usan mcpServers; los clientes que solo admiten stdio siguen necesitando el asistente independiente.

Permisos y puerto

Permitir editar tareas y proyectos permite crear, editar, completar y restaurar tareas, y crear o editar proyectos. En Avanzado, activa Permitir archivar y Permitir eliminar por separado si los necesitas. Cada permiso es independiente y todos empiezan desactivados en una instalación nueva. Las instalaciones existentes que activaron Permitir cambios conservan su permiso de eliminación anterior; puedes desactivarlo sin desactivar la edición. Archivar requiere una nueva autorización explícita.

La herramienta integrada mindwtr_archive_task archiva mediante la operación existente de la aplicación. No completa una tarea ni genera su siguiente recurrencia. Una actualización que combine ediciones habituales con cambios de archivo o cancelación requiere ambos permisos. La eliminación es lógica. Estos ajustes se aplican al servidor integrado, no al asistente independiente ni a la API local separada.

Avanzado también permite elegir un puerto entre 1024 y 65535. Guárdalo y copia los datos de conexión actualizados para tu cliente. Si otro proceso ocupa el puerto, elige uno libre o resuelve el conflicto y usa Volver a intentar. El servidor siempre se vincula a 127.0.0.1.

Los clientes de IA conectados pueden leer los datos expuestos por estas herramientas y enviarlos a su proveedor. Mantén privado el token copiado. Regenerarlo desconecta los clientes existentes, que necesitarán el nuevo token.

Este endpoint sirve a clientes del mismo ordenador. No proporciona acceso remoto desde ChatGPT, un túnel ni un servicio alojado. Las aplicaciones móviles no lo alojan.

Requisitos

Estos requisitos se aplican al asistente independiente.

Node.js 22+ para instalaciones sin compilador: la dependencia de SQLite incluye binarios precompilados para Node 22 y versiones posteriores. Node 20 aún puede ejecutar el servidor, pero las instalaciones necesitan herramientas de compilación de C++
Las instalaciones que solo usan la API pueden omitir el complemento SQLite opcional con --omit=optional.
npm u otro ejecutor de paquetes de Node para el paquete mindwtr-mcp publicado
Una base de datos local de Mindwtr (mindwtr.db) para el modo SQLite, una API local de escritorio en ejecución y su token de portador para el modo API, o una URL autoalojada de Mindwtr Cloud y un token de portador para el modo Cloud
Bun solo si ejecutas el asistente desde el árbol de código fuente

Para el modo SQLite con npm 12, autoriza el script de instalación de la dependencia SQLite; de lo contrario, una instalación correcta puede fallar al iniciar por la ausencia del módulo nativo. Para npx o instalaciones globales, autoriza solo better-sqlite3:

bash

npx --allow-scripts=better-sqlite3 -y mindwtr-mcp --db "/path/to/mindwtr.db"
npm install -g --allow-scripts=better-sqlite3 mindwtr-mcp

En las configuraciones MCP con npx, añade "--allow-scripts=better-sqlite3" antes de "mindwtr-mcp" en args. Para una instalación local existente, ejecuta npm install-scripts approve better-sqlite3 y después npm rebuild better-sqlite3 desde ese proyecto. Revisa la dependencia antes de autorizarla; no habilites todos los scripts.

Ubicaciones predeterminadas de la base de datos

Linux: ~/.local/share/mindwtr/mindwtr.db
Linux (Snap): ~/snap/mindwtr/current/.local/share/mindwtr/mindwtr.db
macOS: ~/Library/Application Support/mindwtr/data/mindwtr.db
Windows: %APPDATA%\mindwtr\data\mindwtr.db

Ruta adicional de macOS para compilaciones aisladas:

~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db

Las rutas de macOS y Windows de arriba son para v1.3.2 y posteriores. Antes de v1.3.2 la base de datos estaba directamente en la carpeta mindwtr, por ejemplo %APPDATA%\mindwtr\mindwtr.db. En Linux no cambió nada.

Puedes sobrescribir la ubicación de la base de datos local con:

--db /path/to/mindwtr.db
Variable de entorno: MINDWTR_DB_PATH o MINDWTR_DB

Para el modo Cloud autoalojado, usa:

--cloud-url https://mindwtr.example.com o MINDWTR_MCP_CLOUD_URL
--cloud-token <token> o MINDWTR_MCP_CLOUD_TOKEN
--cloud-allow-insecure-http=true opcional para despliegues HTTP privados de confianza

Instalación y configuración

Con el asistente independiente, los clientes MCP ejecutan el servidor como subproceso. Debes indicarles el comando y pasar los argumentos.

Comando recomendado sin instalación para clientes MCP:

json

{
  "command": "npx",
  "args": [
    "-y",
    "mindwtr-mcp",
    "--db",
    "/path/to/mindwtr.db"
  ]
}

El paquete es de solo lectura de forma predeterminada. Añade --write únicamente cuando quieras explícitamente que un cliente de IA añada, actualice, complete o elimine datos de Mindwtr.

Modo de API local de escritorio

Requiere mindwtr-mcp 1.1.11 o posterior.

Activa la API local de la aplicación de escritorio en Ajustes y copia su token de portador. Mantén la aplicación y la API en ejecución. Este backend usa los endpoints REST de la aplicación y nunca abre una base de datos ni recurre a SQLite.

Para una instalación que solo use la API, omite el complemento nativo SQLite opcional:

bash

npm install -g --omit=optional mindwtr-mcp

Configura tu cliente MCP para pasar el token mediante su entorno, en lugar de incluirlo en los argumentos de la línea de comandos:

json

{
  "command": "mindwtr-mcp",
  "args": ["--api-url", "http://127.0.0.1:3456"],
  "env": {
    "MINDWTR_MCP_API_TOKEN": "<token from desktop settings>"
  }
}

Usa el puerto que aparece en Ajustes. MINDWTR_MCP_API_URL puede sustituir a --api-url. Las URL deben usar literalmente 127.0.0.1 o [::1], sin credenciales, ruta, consulta ni fragmento; se rechazan las redirecciones. No combines las opciones de API con las de Cloud/--db. En el modo API se ignoran las variables de entorno existentes para rutas de bases de datos.

Las escrituras permanecen desactivadas salvo que se activen explícitamente con --write. Si la aplicación está cerrada o el token no es válido, el asistente devuelve un error. Una escritura cuyo tiempo de espera se haya agotado puede haber llegado a la aplicación: revisa la tarea antes de volver a intentarlo, ya que el asistente no reintenta las escrituras automáticamente.

Capacidad MCP	Compatibilidad de la API local de escritorio
Listar/obtener tareas	Compatible, incluidos operadores de búsqueda avanzados, filtros de fecha, ordenación y paginación
Crear tareas	Título y campos explícitos; `quickAdd` no está disponible
Actualizar/completar/eliminar/restaurar tareas	Compatible mediante los endpoints correspondientes de la API; los cambios a estados finales no pueden enviarse como ediciones ordinarias
Listar/obtener/crear/actualizar/eliminar proyectos	Compatible con los campos básicos de proyecto de la API: título, color, estado, área y comportamiento secuencial
Listar áreas	Compatible
Secciones, personas gestionadas, escrituras de áreas	No disponibles; estas herramientas se ocultan en el modo API
Disponibilidad GTD `view`	No disponible porque la API no expone la instantánea de secciones necesaria
Sustituir enlaces de adjuntos	No disponible porque la API no proporciona actualizaciones condicionales de adjuntos

Los demás campos no compatibles se rechazan antes de escribir. También se aplican las limitaciones de recurrencia de la API de escritorio; algunas tareas recurrentes deben completarse en la aplicación. Este backend no garantiza una equivalencia total con las herramientas SQLite/Cloud.

--api-url selecciona la fuente de datos del asistente. En cambio, --http selecciona cómo se conecta un cliente MCP al asistente; puede usarse con cualquier backend y tiene un token de autenticación independiente.

Modo Cloud autoalojado

Usa el modo Cloud cuando ejecutes tu propio servidor Mindwtr Cloud y quieras disponer de herramientas MCP sin exponer un archivo SQLite local:

bash

npx -y mindwtr-mcp \
  --cloud-url "https://mindwtr.example.com" \
  --cloud-token "$MINDWTR_TOKEN"

O usa variables de entorno en la configuración de un cliente MCP:

json

{
  "command": "npx",
  "args": ["-y", "mindwtr-mcp"],
  "env": {
    "MINDWTR_MCP_CLOUD_URL": "https://mindwtr.example.com",
    "MINDWTR_MCP_CLOUD_TOKEN": "your-token"
  }
}

El modo Cloud lee la instantánea actual de /v1/data desde tu servidor Cloud autoalojado y expone herramientas de lectura para tareas, proyectos, secciones, áreas y personas. Con --write, las escrituras de tareas, proyectos, secciones y áreas pasan por los endpoints REST por recurso del servidor Cloud (POST /v1/tasks, PATCH /v1/tasks/:id, etc.), por lo que cada edición recibe la misma validación y seguimiento de revisiones que las ediciones realizadas desde tus aplicaciones. Sin --write, las herramientas de escritura devuelven read_only. La edición de personas y la restauración de tareas eliminadas aún no están disponibles en el modo Cloud. Usa el backend de base de datos local para esas operaciones.

Actualizar enlaces adjuntos mediante MCP en modo Cloud requiere Mindwtr Cloud 1.2.8 o posterior. El asistente usa escrituras condicionales para conservar los archivos adjuntos que otro cliente haya cambiado y realiza hasta tres intentos ante cambios concurrentes. Si el servidor no proporciona un ETag del registro, actualízalo antes de modificar los enlaces; el asistente rechaza la actualización sin escribir. Las modificaciones de otros campos y la creación de tareas o proyectos mantienen su comportamiento anterior.

Este no es el conector multiusuario alojado que está bloqueado. Sigues ejecutando tú mismo el servidor Cloud y el asistente MCP; Mindwtr no opera un servicio que almacene los datos de tareas de todo el mundo.

Si prefieres una instalación global:

bash

npm install -g mindwtr-mcp
mindwtr-mcp --db "/path/to/mindwtr.db"

Argumentos principales

--db "/path/to/mindwtr.db": Ruta a tu base de datos SQLite para el modo local.
--write: Habilita operaciones de escritura (añadir, actualizar, completar y eliminar) en modo local o Cloud. Sin esta opción, el servidor es de solo lectura.
--cloud-url "https://mindwtr.example.com": Usa un endpoint autoalojado de Mindwtr Cloud en lugar de una base de datos local.
--cloud-token "<token>": Token de portador para el endpoint Cloud autoalojado.
--cloud-allow-insecure-http=true: Permite URL HTTP privadas de confianza cuando se ejecuta intencionadamente sin HTTPS.

1. Claude Desktop

Añade una entrada de servidor al archivo de configuración de Claude Desktop.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "~/.local/share/mindwtr/mindwtr.db",
        "--write"
      ]
    }
  }
}

Nota: Sustituye la ruta de la base de datos por la ruta real de tu base de datos local de Mindwtr.

2. Claude Code (CLI)

Puedes añadir el servidor mediante la CLI:

bash

claude mcp add mindwtr -- \
  npx -y mindwtr-mcp --db "/path/to/mindwtr.db" --write

3. OpenAI Codex (CLI/extensión del IDE)

Codex lee la configuración del servidor MCP desde ~/.codex/config.toml. También puedes usar un archivo .codex/config.toml limitado al proyecto dentro de un proyecto de confianza. La CLI de Codex y la extensión del IDE comparten esta configuración.

Línea de comandos:

bash

codex mcp add mindwtr -- \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db"

Añade --write solo si quieres que Codex modifique datos locales de Mindwtr:

bash

codex mcp add mindwtr -- \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db" --write

En la TUI de Codex, ejecuta /mcp para confirmar que el servidor está activo.

Configuración manual:

toml

[mcp_servers.mindwtr]
command = "npx"
args = [
  "-y",
  "mindwtr-mcp",
  "--db",
  "/path/to/mindwtr.db"
]

Con acceso de escritura:

toml

[mcp_servers.mindwtr]
command = "npx"
args = [
  "-y",
  "mindwtr-mcp",
  "--db",
  "/path/to/mindwtr.db",
  "--write"
]

4. Gemini CLI

Gemini CLI usa settings.json (usuario: ~/.gemini/settings.json o proyecto: .gemini/settings.json).

Línea de comandos:

bash

gemini mcp add mindwtr \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db" --write

Configuración manual:

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "/path/to/mindwtr.db",
        "--write"
      ]
    }
  }
}

5. Aplicación Gemini (apps personalizadas)

Las aplicaciones web y móvil de Gemini pueden conectarse a un servidor MCP remoto mediante una URL ("apps personalizadas" en gemini.google.com). Esto funciona con mindwtr-mcp en modo HTTP: aloja el servidor en un lugar accesible para los servidores de Google (una URL HTTPS pública detrás de un proxy inverso; Gemini se conecta desde el lado de Google, así que localhost no funciona) y añade esa URL como app personalizada junto con tu token bearer.

6. Google Antigravity

Antigravity (el IDE agéntico de Google) lee los servidores MCP locales de un archivo de configuración JSON; no hay comando CLI para añadirlos. Abre el archivo desde el panel lateral del agente mediante MCP Servers -> Manage MCP Servers -> View raw config, o edítalo directamente:

Versiones actuales: ~/.gemini/config/mcp_config.json (por espacio de trabajo: .agents/mcp_config.json)
Versiones antiguas: ~/.gemini/antigravity/mcp_config.json (Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json)

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\mindwtr\\data\\mindwtr.db",
        "--write"
      ]
    }
  }
}

Sustituye la ruta por la de tu base de datos local (las rutas de Windows necesitan barras invertidas dobles en JSON). Omite --write para acceso de solo lectura. Reinicia Antigravity y comprueba que mindwtr aparece en su configuración de servidores MCP. La configuración MCP local de Antigravity es independiente del settings.json de Gemini CLI y de las apps personalizadas de la aplicación Gemini.

Acceso remoto (HTTP)

Requiere una versión de mindwtr-mcp posterior a 1.1.1 (o ejecutar desde el código fuente).

De forma predeterminada, el servidor habla stdio. Pasa --http para servir en su lugar un endpoint MCP de HTTP transmisible, de modo que los clientes MCP remotos puedan conectarse por URL. El modo HTTP funciona con los tres backends (SQLite local, API local de escritorio o Cloud autoalojado).

bash

mindwtr-mcp --http --http-token "$(openssl rand -hex 32)" --db "/path/to/mindwtr.db"

Flags (todas tienen variables de entorno MINDWTR_MCP_HTTP* equivalentes):

Flag	Variable de entorno	Significado
`--http`	`MINDWTR_MCP_HTTP`	Activa el modo HTTP. También queda implícito con cualquiera de las flags siguientes.
`--http-token <token>`	`MINDWTR_MCP_HTTP_TOKEN`	Obligatorio siempre que el modo HTTP esté activo; mínimo 16 caracteres. Genera uno con `openssl rand -hex 32`. Sin token, el servidor se niega a arrancar.
`--http-host <host>`	`MINDWTR_MCP_HTTP_HOST`	Dirección de enlace, por defecto `127.0.0.1`.
`--http-port <port>`	`MINDWTR_MCP_HTTP_PORT`	Puerto de enlace, por defecto `8722`.

El servidor MCP integrado de la aplicación de escritorio también usa el puerto 8722. Si está activado, indica otro puerto con --http-port, por ejemplo --http-port 8723.

El endpoint MCP es POST /mcp y exige Authorization: Bearer <token> en cada petición. GET /healthz devuelve 200 ok sin autenticación para las comprobaciones de salud del proxy inverso. Las peticiones sin token válido reciben 401; los fallos repetidos de autenticación reciben 429 con una cabecera Retry-After. Los cuerpos de más de 1 MiB reciben 413. En modo HTTP el servidor sigue vivo mientras escucha (stdio no se conecta), y el comportamiento de --write/solo lectura no cambia.

No hay TLS ni limitación de velocidad integrados para las peticiones autenticadas. Para exponer el servidor más allá de localhost, coloca delante un proxy inverso (Caddy, nginx) para HTTPS y entrega la URL https:// resultante junto con tu token al cliente MCP remoto.

Ejecución manual

Normalmente no necesitas ejecutarlo de forma manual (el cliente MCP se encarga), pero resulta útil para hacer pruebas.

Desde npm

bash

# Read-only
npx -y mindwtr-mcp --db "/path/to/mindwtr.db"

# With write access
npx -y mindwtr-mcp --db "/path/to/mindwtr.db" --write

Desde el código fuente (Bun)

bash

# Read-only
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

# With write access
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --write

Compilar y ejecutar (Node)

bash

# Build
bun run --filter mindwtr-mcp build

# Run
node apps/mcp-server/dist/cli.js --db "/path/to/mindwtr.db"

Migración: cambio de nombre de las herramientas (`mindwtr.` → `mindwtr_`)

Los nombres de las herramientas ahora usan la notación con guion bajo, como mindwtr_list_tasks; los nombres antiguos con notación de punto ya no se documentan.

Herramientas disponibles

Una vez conectado, el agente de IA tiene acceso a estas herramientas. De forma predeterminada, el servidor es de solo lectura; pasa --write para habilitar cualquier herramienta de escritura. Solo se admite --write para el acceso de escritura (no hay alias alternativos).

Herramienta	Operación	Requiere `--write`
`mindwtr_list_tasks`	Enumerar tareas	No
`mindwtr_list_projects`	Enumerar proyectos	No
`mindwtr_get_project`	Obtener un proyecto	No
`mindwtr_list_sections`	Enumerar secciones	No
`mindwtr_get_section`	Obtener una sección	No
`mindwtr_list_areas`	Enumerar áreas	No
`mindwtr_list_people`	Enumerar personas	No
`mindwtr_get_person`	Obtener una persona	No
`mindwtr_get_task`	Obtener una tarea por ID	No
`mindwtr_add_task`	Crear una tarea	Sí
`mindwtr_update_task`	Actualizar una tarea	Sí
`mindwtr_complete_task`	Marcar como completada	Sí
`mindwtr_delete_task`	Eliminar una tarea de forma lógica	Sí
`mindwtr_restore_task`	Restaurar una tarea	Sí
`mindwtr_add_project`	Crear un proyecto	Sí
`mindwtr_update_project`	Actualizar un proyecto	Sí
`mindwtr_delete_project`	Eliminar un proyecto de forma lógica	Sí
`mindwtr_add_section`	Crear una sección	Sí
`mindwtr_update_section`	Actualizar una sección	Sí
`mindwtr_delete_section`	Eliminar una sección de forma lógica	Sí
`mindwtr_add_area`	Crear un área	Sí
`mindwtr_update_area`	Actualizar un área	Sí
`mindwtr_delete_area`	Eliminar un área de forma lógica	Sí
`mindwtr_add_person`	Crear una persona	Sí
`mindwtr_update_person`	Actualizar una persona	Sí
`mindwtr_rename_person`	Cambiar el nombre de una persona	Sí
`mindwtr_delete_person`	Eliminar una persona de forma lógica	Sí

Herramientas de lectura

mindwtr_list_tasks: Enumera tareas con filtros (estado, proyecto, intervalo de fechas, búsqueda, isFocusedToday para el foco de hoy y view para la disponibilidad GTD).
mindwtr_list_projects: Enumera todos los proyectos.
mindwtr_get_project: Obtiene los detalles de un proyecto concreto por ID.
mindwtr_list_sections: Enumera las secciones de los proyectos, con filtro opcional por proyecto.
mindwtr_get_section: Obtiene los detalles de una sección concreta por ID.
mindwtr_list_areas: Enumera todas las áreas.
mindwtr_list_people: Enumera los registros de personas gestionadas.
mindwtr_get_person: Obtiene los detalles de una persona concreta por ID.
mindwtr_get_task: Obtiene los detalles de una tarea concreta por ID.

Herramientas de escritura (requieren `--write`)

Las herramientas de escritura funcionan tanto con la base de datos local como con un backend Cloud autoalojado, con dos excepciones en modo Cloud: las herramientas de escritura de personas y mindwtr_restore_task devuelven un error claro en modo Cloud porque la API de Cloud aún no dispone de endpoints para ellas.

mindwtr-mcp permite conservar o cambiar el título de un enlace existente a un recurso compartido de red al actualizar una tarea o un proyecto. Mantén la URI exactamente igual y reutiliza el ID del adjunto, u omite el ID para buscar la coincidencia por URI. El enlace debe seguir activo en ese mismo elemento. MCP seguirá rechazando enlaces nuevos a recursos compartidos de red, cambios de sus URI y la restauración de enlaces de red eliminados.

mindwtr_add_task: Crea una tarea nueva. Admite lenguaje natural en quickAdd (por ejemplo, "Buy milk @errands /due:tomorrow"). También admite adjuntos de enlace mediante attachments.
mindwtr_update_task: Actualiza una tarea existente, incluidos campos de programación como dueDate, startTime, reviewAt e isFocusedToday (permite borrar campos con null). attachments define los adjuntos de enlace: la lista que envías es el conjunto completo de enlaces, los enlaces que omitas se eliminan, los adjuntos de archivo nunca se tocan y null borra todos los enlaces.
mindwtr_complete_task: Marca una tarea como completada.
mindwtr_delete_task: Elimina una tarea de forma lógica.
mindwtr_restore_task: Restaura una tarea eliminada de forma lógica.
mindwtr_add_project: Crea un proyecto nuevo, incluidos startDate, dueDate y reviewAt opcionales. También acepta adjuntos de enlace mediante attachments.
mindwtr_update_project: Actualiza un proyecto, incluidos startDate, dueDate y reviewAt opcionales. Los adjuntos de enlace en attachments siguen la misma regla de lista completa que al actualizar una tarea.
mindwtr_delete_project: Elimina un proyecto de forma lógica.
mindwtr_add_section: Crea una sección dentro de un proyecto.
mindwtr_update_section: Actualiza una sección de un proyecto.
mindwtr_delete_section: Elimina una sección de un proyecto de forma lógica. Las tareas de esa sección se conservan y core las mueve para que no pertenezcan a ninguna sección.
mindwtr_add_area: Crea un área nueva.
mindwtr_update_area: Actualiza un área.
mindwtr_delete_area: Elimina un área de forma lógica.
mindwtr_add_person: Crea una persona gestionada para responsables y tareas en espera.
mindwtr_update_person: Actualiza los metadatos de una persona gestionada.
mindwtr_rename_person: Cambia el nombre de una persona gestionada y, opcionalmente, actualiza las asignaciones exactas de tareas.
mindwtr_delete_person: Elimina una persona gestionada de forma lógica sin borrar las asignaciones de tareas.

Nota sobre el esquema:

Las herramientas de escritura de tareas cubren dueDate, startTime y reviewAt (al actualizar).
Las herramientas de escritura de proyectos cubren tanto dueDate como reviewAt.
Las herramientas de escritura de personas cubren name, note, referenceLink y actualizaciones opcionales de asignaciones al cambiar el nombre.
Para consultar las entradas canónicas exactas, usa apps/mcp-server/README.md.

Matriz de permisos

Usa esta matriz para decidir si ejecutar el servidor en modo de solo lectura o con --write.

Herramienta	Acceso a datos	Tipo de modificación	Modo de solo lectura	Modo `--write`
`mindwtr_list_tasks`	Filas de tareas (filtradas)	Ninguna	Permitido	Permitido
`mindwtr_list_projects`	Filas de proyectos	Ninguna	Permitido	Permitido
`mindwtr_get_project`	Un proyecto por ID	Ninguna	Permitido	Permitido
`mindwtr_list_sections`	Filas de secciones	Ninguna	Permitido	Permitido
`mindwtr_get_section`	Una sección por ID	Ninguna	Permitido	Permitido
`mindwtr_list_areas`	Filas de áreas	Ninguna	Permitido	Permitido
`mindwtr_list_people`	Filas de personas	Ninguna	Permitido	Permitido
`mindwtr_get_person`	Una persona por ID	Ninguna	Permitido	Permitido
`mindwtr_get_task`	Una tarea por ID	Ninguna	Permitido	Permitido
`mindwtr_add_task`	Tabla de tareas	Inserción	Denegado	Permitido
`mindwtr_update_task`	Tabla de tareas	Actualización	Denegado	Permitido
`mindwtr_complete_task`	Tabla de tareas	Actualización del estado	Denegado	Permitido
`mindwtr_delete_task`	Tabla de tareas	Eliminación lógica	Denegado	Permitido
`mindwtr_restore_task`	Tabla de tareas	Restauración de eliminación lógica	Denegado	Permitido
`mindwtr_add_project`	Tabla de proyectos	Inserción	Denegado	Permitido
`mindwtr_update_project`	Tabla de proyectos	Actualización	Denegado	Permitido
`mindwtr_delete_project`	Tabla de proyectos	Eliminación lógica	Denegado	Permitido
`mindwtr_add_section`	Tabla de secciones	Inserción	Denegado	Permitido
`mindwtr_update_section`	Tabla de secciones	Actualización	Denegado	Permitido
`mindwtr_delete_section`	Tabla de secciones	Eliminación lógica	Denegado	Permitido
`mindwtr_add_area`	Tabla de áreas	Inserción	Denegado	Permitido
`mindwtr_update_area`	Tabla de áreas	Actualización	Denegado	Permitido
`mindwtr_delete_area`	Tabla de áreas	Eliminación lógica	Denegado	Permitido
`mindwtr_add_person`	Tabla de personas	Inserción	Denegado	Permitido
`mindwtr_update_person`	Tabla de personas	Actualización	Denegado	Permitido
`mindwtr_rename_person`	Tabla de personas/tareas	Cambio de nombre/actualización de referencias	Denegado	Permitido
`mindwtr_delete_person`	Tabla de personas	Eliminación lógica	Denegado	Permitido

Orientación práctica:

Usa el modo de solo lectura de forma predeterminada para la exploración y los informes.
Habilita --write solo para backends que confíes al cliente de IA para su edición: una base de datos local o tu propio servidor Cloud.
Para flujos de trabajo con agentes, es preferible pedir confirmación explícita antes de las operaciones de eliminación o finalización.

Ejemplos de uso avanzado

1) Revisión semanal guiada

mindwtr_list_tasks con status: "waiting" y status: "someday".
Resume los elementos estancados por proyecto.
Para los elementos seleccionados, llama a mindwtr_update_task para establecer reviewAt.

2) Sesión de clasificación de la bandeja de entrada

mindwtr_list_tasks con status: "inbox" y sortBy: "createdAt".
Para cada tarea, clasifícala con mindwtr_update_task (next, waiting, reference, etc.).
Añade los metadatos que falten (proyecto, contextos y etiquetas) en una segunda pasada.

3) Patrón seguro para cierres masivos

Para automatizaciones potencialmente destructivas:

Ejecuta la fase de lectura: enumera únicamente los ID candidatos.
Presenta un resumen de confirmación (cantidad y títulos).
Ejecuta las escrituras (complete_task / delete_task) solo después de recibir la aprobación explícita del usuario.
Conserva los ID para poder revertir mediante restore_task.

4) Captura rápida con lenguaje natural

Usa mindwtr_add_task + quickAdd:

json

{
  "quickAdd": "Follow up with Alex +Hiring @work #ops /due:tomorrow 10am"
}

Úsalo para flujos de captura rápida en los que analizar comandos sea más eficiente que establecer cada campo manualmente.

Referencia de herramientas

Todas las herramientas devuelven JSON en el campo content.text. Analiza el JSON para obtener la carga útil real.

Límites operativos

Estos límites son útiles al integrar Mindwtr en flujos de trabajo con agentes:

mindwtr_list_tasks usa limit: 200 de forma predeterminada y limita limit a 500.
Los títulos de las tareas están limitados a 500 caracteres en la validación de creación/actualización de tareas mediante MCP.
Las entradas de adición rápida están limitadas a 2000 caracteres al crear tareas mediante MCP, igual que el límite de adición rápida de la API de tareas de Cloud.
La capa de SQLite usa un busy_timeout de 5 segundos, por lo que una base de datos bloqueada debería fallar en vez de quedar colgada indefinidamente.

Si necesitas más de 500 tareas, pagina con limit + offset en lugar de esperar una única respuesta sin límite.

`mindwtr_list_tasks`

Campos de entrada

status: inbox | next | waiting | someday | reference | done | archived | all
projectId: string
includeDeleted: boolean
limit: number
offset: number
search: string
dueDateFrom: ISO date or datetime string (comparada por fecha del calendario)
dueDateTo: ISO date or datetime string (comparada por fecha del calendario)
isFocusedToday: boolean
view: available | deferred | blocked — Disponibilidad GTD. available = accionable ahora mismo (una próxima acción, o una tarea cuya fecha de revisión ya venció, en un proyecto activo, pasada cualquier fecha de inicio y sin esperar detrás de un paso anterior de un proyecto secuencial). deferred = la fecha de inicio todavía está en el futuro. blocked = un paso anterior de un proyecto secuencial ocupa el turno.
sortBy: updatedAt | createdAt | dueDate | title | priority
sortOrder: asc | desc

Ejemplo

json

{
  "status": "next",
  "limit": 20,
  "offset": 0,
  "sortBy": "updatedAt",
  "sortOrder": "desc"
}

Respuesta

json

{
  "tasks": [
    {
      "id": "task-uuid",
      "title": "Follow up with design",
      "status": "next",
      "updatedAt": "2026-01-25T03:45:57.246Z"
    }
  ]
}

`mindwtr_list_projects`

Campos de entrada

ninguno

Respuesta

json

{
  "projects": [
    {
      "id": "project-uuid",
      "title": "Mindwtr",
      "status": "active"
    }
  ]
}

`mindwtr_get_project`

Campos de entrada

id: string (UUID del proyecto)
includeDeleted: boolean (opcional)

Ejemplo

json

{ "id": "project-uuid" }

`mindwtr_list_sections`

Campos de entrada

projectId: string (opcional)
includeDeleted: boolean (opcional)

Respuesta

json

{
  "sections": [
    {
      "id": "section-uuid",
      "projectId": "project-uuid",
      "title": "Planning"
    }
  ]
}

`mindwtr_get_section`

Campos de entrada

id: string (UUID de la sección)
includeDeleted: boolean (opcional)

Ejemplo

json

{ "id": "section-uuid" }

`mindwtr_list_areas`

Campos de entrada

ninguno

Respuesta

json

{
  "areas": [
    {
      "id": "area-uuid",
      "name": "Work"
    }
  ]
}

`mindwtr_list_people`

Campos de entrada

includeDeleted: boolean (opcional)

Respuesta

json

{
  "people": [
    {
      "id": "person-uuid",
      "name": "Alex"
    }
  ]
}

`mindwtr_get_person`

Campos de entrada

id: string (UUID de la persona)
includeDeleted: boolean (opcional)

Ejemplo

json

{ "id": "person-uuid" }

`mindwtr_get_task`

Campos de entrada

id: string (UUID de la tarea)
includeDeleted: boolean (opcional)

Ejemplo

json

{ "id": "task-uuid" }

`mindwtr_add_task` (escritura)

Campos de entrada

title: string (obligatorio si se omite quickAdd)
quickAdd: string (obligatorio si se omite title)
status: inbox | next | waiting | someday | reference | done | archived
projectId: string
sectionId: string
dueDate: ISO string
startTime: ISO string
recurrence: objeto de recurrencia o cadena RRULE de RFC 5545
contexts: string[]
tags: string[]
description: string
priority: low | medium | high | urgent
energyLevel: low | medium | high
assignedTo: string
timeEstimate: 5min | 10min | 15min | 30min | 1hr | 2hr | 3hr | 4hr | 4hr+
Otros campos editables: areaId, reviewAt, taskMode, relativeStartOffset, showFutureRecurrence, pushCount, checklist, textDirection, location, isFocusedToday, timeSpentMinutes, suppressMindwtrReminders, repeatReminderMinutes, attachments

Ejemplo

json

{
  "quickAdd": "Send invoice +Acme /due:tomorrow 9am #finance"
}

`mindwtr_update_task` (escritura)

Campos de entrada

id: string (UUID de la tarea)
title, status, projectId, sectionId, areaId, dueDate, startTime, contexts, tags, description, priority, energyLevel, assignedTo, timeEstimate, reviewAt, taskMode, relativeStartOffset, showFutureRecurrence, pushCount, checklist, textDirection, location, isFocusedToday, timeSpentMinutes, suppressMindwtrReminders, repeatReminderMinutes, order, boardOrder, focusOrder, attachments
recurrence: objeto de recurrencia, cadena RRULE de RFC 5545 o null para borrarla

Notas

Usa null para borrar campos que admiten valores nulos. Esto se aplica a campos de tarea como projectId, dueDate, startTime, contexts y tags; campos de proyecto como areaId, startDate, dueDate, reviewAt y supportNotes; el campo description de las secciones; los campos color e icon de las áreas; y los campos note y referenceLink de las personas.

Ejemplo

json

{
  "id": "task-uuid",
  "status": "waiting",
  "reviewAt": "2026-01-27T09:00:00.000Z"
}

`mindwtr_complete_task` (escritura)

Campos de entrada

id: string (UUID de la tarea)

`mindwtr_delete_task` (escritura)

Campos de entrada

id: string (UUID de la tarea)

`mindwtr_restore_task` (escritura)

Campos de entrada

id: string (UUID de la tarea)

`mindwtr_add_project` (escritura)

Campos de entrada

title: string
color: string (opcional)
status: active | someday | waiting | archived (opcional)
areaId: string or null
isSequential: boolean (opcional)
isFocused: boolean (opcional)
startDate: ISO string or null
dueDate: ISO string or null
reviewAt: ISO string or null
supportNotes: string or null

`mindwtr_update_project` (escritura)

Campos de entrada

id: string (UUID del proyecto)
title, color, status, areaId, isSequential, isFocused, startDate, dueDate, reviewAt, supportNotes, attachments

`mindwtr_delete_project` (escritura)

Campos de entrada

id: string (UUID del proyecto)

`mindwtr_add_section` (escritura)

Campos de entrada

projectId: string
title: string
description: string or null (opcional)
order: number (opcional)
isCollapsed: boolean (opcional)

`mindwtr_update_section` (escritura)

Campos de entrada

id: string (UUID de la sección)
title, description, order, isCollapsed

`mindwtr_delete_section` (escritura)

Campos de entrada

id: string (UUID de la sección)

`mindwtr_add_area` (escritura)

Campos de entrada

name: string
color: string (opcional)
icon: string (opcional)

`mindwtr_update_area` (escritura)

Campos de entrada

id: string (UUID del área)
name, color, icon

`mindwtr_delete_area` (escritura)

Campos de entrada

id: string (UUID del área)

`mindwtr_add_person` (escritura)

Campos de entrada

name: string
note: string or null (opcional)
referenceLink: string or null (opcional)

`mindwtr_update_person` (escritura)

Campos de entrada

id: string (UUID de la persona)
name, note, referenceLink

`mindwtr_rename_person` (escritura)

Campos de entrada

id: string (UUID de la persona)
name: string
updateTasks: boolean (opcional)

`mindwtr_delete_person` (escritura)

Campos de entrada

id: string (UUID de la persona)

Notas sobre el formato de salida

Las salidas de las herramientas son cadenas JSON, no valores MCP estructurados. Tu cliente debe analizar content[0].text.
Los ID de tareas/proyectos son UUID de la base de datos SQLite local.
Las fechas son cadenas ISO 8601 (UTC).

Seguridad y notas

Concurrencia (modo SQLite local): El servidor usa el modo WAL de SQLite y reintenta los conflictos de bloqueo transitorios ejecutando de nuevo la escritura con los datos actuales. El cliente solo necesita reintentar si se agotan esos intentos.
Lógica compartida: Las operaciones de escritura usan la biblioteca compartida @mindwtr/core para garantizar que se apliquen las reglas de negocio.
Persistencia: En modo stdio, el servidor permanece activo mientras stdin esté abierto. En modo HTTP, permanece activo mientras el listener esté en ejecución.

`cancelledAt`

Task y Project admiten cancelledAt, una marca de tiempo ISO opcional con zona horaria. Archiva el compromiso como cancelado. La tarea no tiene completedAt ni genera otra repetición. Al cancelar un proyecto se conservan los pasos completados y se cancelan las acciones restantes. Actualiza todos los clientes que escriban datos antes de sincronizar. Consulta el flujo GTD.

cancelledAt: null por sí solo borra la marca sin reactivar el elemento. Para reactivarlo, establece explícitamente un status no archivado.

Solución de problemas

"Command not found": Usa npx -y mindwtr-mcp en las configuraciones de los clientes MCP o instala el paquete globalmente con npm install -g mindwtr-mcp.
Problemas de conexión del cliente: Asegúrate de NO usar bun run como comando en la configuración del cliente MCP, ya que puede generar texto adicional. Es preferible usar npx -y mindwtr-mcp; para copias del código fuente, ejecuta bun directamente sobre el archivo fuente o node sobre el archivo compilado.

Servidor MCP ​

Binarios de la aplicación frente al asistente MCP ​

MCP integrado en escritorio ​

Conectar Codex ​

Permisos y puerto ​

Requisitos ​

Ubicaciones predeterminadas de la base de datos ​

Instalación y configuración ​

Modo de API local de escritorio ​

Modo Cloud autoalojado ​

Argumentos principales ​

1. Claude Desktop ​

2. Claude Code (CLI) ​

3. OpenAI Codex (CLI/extensión del IDE) ​

4. Gemini CLI ​

5. Aplicación Gemini (apps personalizadas) ​

6. Google Antigravity ​

Acceso remoto (HTTP) ​

Ejecución manual ​

Desde npm ​

Desde el código fuente (Bun) ​

Compilar y ejecutar (Node) ​

Migración: cambio de nombre de las herramientas (mindwtr.* → mindwtr_*) ​

Herramientas disponibles ​

Herramientas de lectura ​

Herramientas de escritura (requieren --write) ​

Matriz de permisos ​

Ejemplos de uso avanzado ​

1) Revisión semanal guiada ​

2) Sesión de clasificación de la bandeja de entrada ​

3) Patrón seguro para cierres masivos ​

4) Captura rápida con lenguaje natural ​

Referencia de herramientas ​

Límites operativos ​

mindwtr_list_tasks ​

mindwtr_list_projects ​

mindwtr_get_project ​

mindwtr_list_sections ​

mindwtr_get_section ​

mindwtr_list_areas ​

mindwtr_list_people ​

mindwtr_get_person ​

mindwtr_get_task ​

mindwtr_add_task (escritura) ​

mindwtr_update_task (escritura) ​

mindwtr_complete_task (escritura) ​

mindwtr_delete_task (escritura) ​

mindwtr_restore_task (escritura) ​

mindwtr_add_project (escritura) ​

mindwtr_update_project (escritura) ​

mindwtr_delete_project (escritura) ​

mindwtr_add_section (escritura) ​

mindwtr_update_section (escritura) ​

mindwtr_delete_section (escritura) ​

mindwtr_add_area (escritura) ​

mindwtr_update_area (escritura) ​

mindwtr_delete_area (escritura) ​

mindwtr_add_person (escritura) ​

mindwtr_update_person (escritura) ​

mindwtr_rename_person (escritura) ​

mindwtr_delete_person (escritura) ​

Notas sobre el formato de salida ​

Seguridad y notas ​

cancelledAt ​

Solución de problemas ​

Servidor MCP

Binarios de la aplicación frente al asistente MCP

MCP integrado en escritorio

Conectar Codex

Permisos y puerto

Requisitos

Ubicaciones predeterminadas de la base de datos

Instalación y configuración

Modo de API local de escritorio

Modo Cloud autoalojado

Argumentos principales

1. Claude Desktop

2. Claude Code (CLI)

3. OpenAI Codex (CLI/extensión del IDE)

4. Gemini CLI

5. Aplicación Gemini (apps personalizadas)

6. Google Antigravity

Acceso remoto (HTTP)

Ejecución manual

Desde npm

Desde el código fuente (Bun)

Compilar y ejecutar (Node)

Migración: cambio de nombre de las herramientas (`mindwtr.` → `mindwtr_`)

Herramientas disponibles

Herramientas de lectura

Herramientas de escritura (requieren `--write`)

Matriz de permisos

Ejemplos de uso avanzado

1) Revisión semanal guiada

2) Sesión de clasificación de la bandeja de entrada

3) Patrón seguro para cierres masivos

4) Captura rápida con lenguaje natural

Referencia de herramientas

Límites operativos

`mindwtr_list_tasks`

`mindwtr_list_projects`

`mindwtr_get_project`

`mindwtr_list_sections`

`mindwtr_get_section`

`mindwtr_list_areas`

`mindwtr_list_people`

`mindwtr_get_person`

`mindwtr_get_task`

`mindwtr_add_task` (escritura)

`mindwtr_update_task` (escritura)

`mindwtr_complete_task` (escritura)

`mindwtr_delete_task` (escritura)

`mindwtr_restore_task` (escritura)

`mindwtr_add_project` (escritura)

`mindwtr_update_project` (escritura)

`mindwtr_delete_project` (escritura)

`mindwtr_add_section` (escritura)

`mindwtr_update_section` (escritura)

`mindwtr_delete_section` (escritura)

`mindwtr_add_area` (escritura)

`mindwtr_update_area` (escritura)

`mindwtr_delete_area` (escritura)

`mindwtr_add_person` (escritura)

`mindwtr_update_person` (escritura)

`mindwtr_rename_person` (escritura)

`mindwtr_delete_person` (escritura)

Notas sobre el formato de salida

Seguridad y notas

`cancelledAt`

Solución de problemas