Obsidian Developer Memory MCP

Un servidor local de Model Context Protocol que proporciona memoria de ingeniería persistente a asistentes de codificación de IA como Cursor y GitHub Copilot.

La memoria se almacena como archivos Markdown ordinarios en un vault de Obsidian. Obsidian no necesita estar en ejecución. No hay plugin de comunidad ni clave de API de Obsidian.

El mismo servidor MCP stdio funciona tanto con Cursor como con GitHub Copilot / VS Code.

Arquitectura

Cursor Agent --------------------\
                                  \
                                   > MCP stdio server
                                  /        |
GitHub Copilot / VS Code --------/         v
                               obsidian-dev-memory
                                        |
                                        v
                               Obsidian Markdown Vault

Developer opens spring-auth in Cursor
        |
        v
Cursor calls get_project_context("spring-auth")
        |
        v
AI sees current project state + recent decisions
        |
        v
Developer and AI implement feature
        |
        v
AI calls capture_work_session(...)
        |
        +--> session note
        |
        +--> Git branch/SHA recorded
        |
        v
Durable architecture choice?
        |
       yes
        |
        v
record_decision(...)

Related MCP server: LumenCore

¿Por qué Markdown directo?

El vault es la fuente de verdad. Las notas siguen siendo legibles y editables en Obsidian, git o cualquier editor de texto. El servidor nunca depende de que Obsidian esté abierto, nunca se comunica con una API de memoria alojada y nunca escribe una base de datos propietaria.

Requisitos

• Python 3.12+

• uv

• Un directorio de vault de Obsidian local

• Git en PATH solo si quieres instantáneas automáticas del repositorio

Instalación

git clone https://github.com/jmjava/obsidian-mcp.git
cd obsidian-mcp
uv sync

uv sync instala el SDK oficial de MCP para Python y el paquete del proyecto.

Configuración

Requerido:

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"

Opcional:

export OBSIDIAN_MEMORY_ROOT="AI Memory"

OBSIDIAN_MEMORY_ROOT tiene como valor predeterminado AI Memory. La configuración MCP del editor puede suministrar estas variables directamente. Este proyecto incluye .env.example como documentación; el servidor no carga automáticamente archivos .env.

Ejecutar el servidor

export OBSIDIAN_VAULT_PATH="/tmp/example-vault"
mkdir -p "$OBSIDIAN_VAULT_PATH"

uv run python -m obsidian_dev_memory

o:

uv run obsidian-dev-memory

El proceso habla MCP a través de stdio. No escribas registros de aplicación en stdout; los diagnósticos van a stderr.

Configuración de Cursor

La configuración de Cursor a nivel de proyecto se encuentra en .cursor/mcp.json y utiliza el formato actual mcpServers. Una plantilla portátil está en config/cursor.mcp.json.example:

{
  "mcpServers": {
    "obsidian-dev-memory": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/obsidian-dev-memory-mcp",
        "run",
        "python",
        "-m",
        "obsidian_dev_memory"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/ABSOLUTE/PATH/TO/OBSIDIAN/VAULT"
      }
    }
  }
}

Este repositorio también incluye .cursor/rules/obsidian-memory.mdc, que le indica a Cursor cuándo leer y escribir memoria.

Los archivos .cursor/mcp.json específicos de cada máquina los crea el instalador y no se confirman aquí.

Configuración de GitHub Copilot / VS Code

La configuración de Copilot / VS Code del espacio de trabajo se encuentra en .vscode/mcp.json y utiliza el formato actual servers. Una plantilla portátil está en config/vscode.mcp.json.example:

{
  "servers": {
    "obsidian-dev-memory": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/obsidian-dev-memory-mcp",
        "run",
        "python",
        "-m",
        "obsidian_dev_memory"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/ABSOLUTE/PATH/TO/OBSIDIAN/VAULT"
      }
    }
  }
}

.github/copilot-instructions.md le da a Copilot el mismo comportamiento de memoria que a Cursor.

Uso del instalador

Conecta este servidor a otro proyecto de desarrollo:

./scripts/install-project.sh \
  --project /home/user/src/example \
  --vault /home/user/Documents/ObsidianVault

Opcional:

./scripts/install-project.sh \
  --project /home/user/src/example \
  --vault /home/user/Documents/ObsidianVault \
  --server /path/to/obsidian-dev-memory-mcp

Si se omite --server, el script infiere este repositorio desde su propia ubicación.

El instalador crea o actualiza:

• <project>/.cursor/mcp.json

• <project>/.cursor/rules/obsidian-memory.mdc

• <project>/.vscode/mcp.json

• <project>/.github/copilot-instructions.md

Falla de forma clara cuando falta el proyecto o el vault de destino, y fusiona el JSON de MCP para que no se destruyan servidores no relacionados.

Herramientas MCP

get_project_context devuelve secciones vacías cuando un proyecto es nuevo en lugar de fallar.

record_decision escribe YYYY-MM-DD-<decision-slug>.md. Si ese archivo ya existe, el servidor añade un sufijo numérico (-2, -3, ...) en lugar de sobrescribirlo.

capture_work_session acepta un repository_path opcional. Cuando esa ruta es un repositorio Git, la nota registra el nombre del repositorio, la rama, el SHA corto, el estado de modificación y una lista breve de archivos modificados. Nunca se escriben diffs completos. Una ruta que no es Git se ignora.

Estructura del vault

AI Memory/
└── Projects/
    └── <project-slug>/
        ├── Project State.md
        ├── Sessions/
        │   └── YYYY-MM-DD.md
        └── Decisions/
            └── YYYY-MM-DD-<decision-slug>.md

Daily/
└── YYYY-MM-DD.md

La carpeta AI Memory respeta OBSIDIAN_MEMORY_ROOT. Los nombres lógicos de proyectos se convierten en slugs (Spring Authorization Server → spring-authorization-server).

Flujo de trabajo de ejemplo

1. Abre un proyecto en Cursor o VS Code.

2. Antes de un trabajo sustancial, el asistente llama a get_project_context.

3. Después de una implementación significativa, llama a capture_work_session.

4. Cuando se toma una decisión de arquitectura, llama a record_decision.

5. Cuando cambia el estado general, llama a update_project_state.

6. Abre el vault en Obsidian en cualquier momento para leer o editar los mismos archivos.

Modelo de seguridad

• Todas las rutas de notas deben resolverse dentro de OBSIDIAN_VAULT_PATH.

• Se rechazan las rutas absolutas, el recorrido ../ y las fugas de enlaces simbólicos detectables.

• Las escrituras son atómicas (tempfile + os.replace) cuando es práctico.

• Las herramientas no son una API general de sistema de archivos.

• Los valores con aspecto de secreto (claves, tokens, JWT, claves privadas, asignaciones password=) se reemplazan con [redacted-secret] antes de escribirse.

• Las reglas de Cursor y las instrucciones de Copilot le indican al asistente que nunca persista contraseñas, claves de API, tokens, JWT, claves privadas, contenido de .env, credenciales de bases de datos, secretos de producción ni datos sensibles de clientes.

Pruebas

Las pruebas usan directorios temporales, nunca tu vault real.

uv run pytest

Una comprobación local más amplia:

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"
./scripts/smoke-test.sh

La prueba de humo verifica la variable de entorno, el directorio del vault, la importación del paquete, la construcción del servidor y la suite de pytest.

Solución de problemas

Licencia

MIT. Consulta LICENSE.