agent-notes-mcp

agent-notes-mcp es un servidor local MCP stdio para buscar y editar de forma segura notas personales en Markdown desde clientes MCP como Codex.

Usa la búsqueda de texto completo habitual sobre nombres de archivo, frontmatter YAML y el cuerpo del Markdown. No necesita bases de datos vectoriales ni modelos de embedding.

Funciones principales

• Búsqueda, listado y lectura de notas Markdown dentro del root configurado.

• Creación, adición, reemplazo y movimiento de notas dentro de un root de escritura.

• Detección de conflictos mediante SHA-256 al reemplazar o mover notas.

• Actualización masiva segura de los bloques Markdown marcados explícitamente.

• Actualización por lotes arbitraria, registro de fecha y hora de actualización y registro de actividad.

• No se ofrecen operaciones de borrado ni escucha de red.

Consulta el modelo de seguridad para conocer los límites de acceso y las garantías de actualización.

Related MCP server: Notes — local markdown knowledge base

Requisitos

• Python 3.14 o superior

• uv

Instalación

Para instalar desde un checkout local:

uv tool install .

Para instalar desde la rama main de GitHub:

uv tool install git+https://github.com/mitszo/agent-notes-mcp.git

Para usar un commit o una etiqueta concreta, añade @<ref> al final de la URL.

Configuración

Copia el ejemplo de configuración y sustituye cada ruta por el directorio que administres.

mkdir -p ~/.config/agent-notes-mcp
cp config.example.toml ~/.config/agent-notes-mcp/config.toml

read_roots permite buscar y leer. write_roots permite buscar, leer y editar, y deben estar dentro de un root de lectura. Empieza con un root de escritura limitado, como inbox o memos.

Registro en Codex

Registra el comando instalado como servidor MCP stdio.

[mcp_servers.agent_notes]
command = "agent_notes"

Si usas un checkout del código fuente, indica el archivo de configuración.

[mcp_servers.agent_notes]
command = "uv"
args = ["run", "agent_notes", "--config", "/absolute/path/to/config.toml"]

Primeros 5 minutos

Abre un hilo nuevo en Codex y pídele primero algo como esto:

agent_notes で設定済みの root を確認し、ノートを検索できるか試してください。

Codex puede usar herramientas MCP como list_roots, search_notes y read_note. Para probar la escritura, pídele que cree un archivo Markdown de prueba dentro del write_roots limitado que hayas permitido en la configuración.

Si usas las notas para traspasar el contexto entre varios repositorios de desarrollo, consulta el ejemplo de contexto de proyecto para Codex y el ejemplo de skill, que puedes copiar y ajustar. Esta práctica es opcional; el servidor no impone la ubicación ni el formato de las notas.

Actualizaciones seguras

Antes de reemplazar o mover una nota existente, léela y especifica el sha256 devuelto como expected_sha256. Si el contenido cambia mientras tanto, el servidor rechaza la actualización sin sobrescribirla.

Para limitar el ámbito en el que se permiten actualizaciones dentro de una nota, delimítalo con bloques gestionados.

<!-- agent-notes:managed next-actions -->
## 次の行動

- 下書きを確認する
<!-- /agent-notes:managed next-actions -->

update_managed_blocks actualiza únicamente los bloques gestionados cuya estructura se puede validar. batch_update_notes valida todas las actualizaciones de destino antes de comenzar a escribir.

Desarrollo

uv sync --all-groups
uv run pytest

Licencia

MIT

Acerca del desarrollo

Este proyecto utiliza Codex como apoyo para el desarrollo. El mantenedor revisa el contenido y toma las decisiones antes de publicarlo.