harper-obsidian. Tu vault de Obsidian accesible desde Claude Code

Obsidian es donde vive el conocimiento: notas, documentación, proyectos, ideas. Claude Code es donde ocurre el trabajo. Con harper-obsidian, el asistente puede leer y escribir en tu vault directamente — sin copiar y pegar, sin cambiar de ventana.

Este es el segundo artículo de la serie MCP en el homelab. Si no has leído el primero, empieza por ahí para entender el contexto.

🔧 Instalación

pip install mcp

Eso es todo. El servidor no necesita nada más — la librería mcp gestiona el protocolo y el vault es un directorio de ficheros Markdown estándar.

⚙️ Configuración

Variable de entorno

export OBSIDIAN_VAULT=/home/usuario/Obsidian

Si no se define, el servidor usa ~/Obsidian por defecto.

Añadir a Claude Code

En ~/.claude.json:

{
  "mcpServers": {
    "harper-obsidian": {
      "type": "stdio",
      "command": "python3",
      "args": ["/ruta/a/harper-mcps/mcp_obsidian_server.py"],
      "env": {
        "OBSIDIAN_VAULT": "/home/usuario/Obsidian"
      }
    }
  }
}

Si usas conda o venv, sustituye python3 por la ruta al intérprete del entorno.

🛠️ Herramientas disponibles

search_vault

Busca texto en todas las notas. Devuelve el nombre de la nota, la ruta y un fragmento de ±100 caracteres alrededor del match.

¿Qué notas tengo sobre Proxmox?
→ search_vault("Proxmox")

read_note

Lee una nota completa: frontmatter parseado + contenido. La ruta es relativa al vault.

Lee la nota 06-Janet/hypervisors/r2d2.md
→ read_note("06-Janet/hypervisors/r2d2.md")

write_note

Escribe o sobreescribe una nota. Si la ruta no existe, la crea junto con los directorios necesarios.

Crea una nota en 03-Notas/reunion-2026-05-16.md con este contenido: ...
→ write_note("03-Notas/reunion-2026-05-16.md", contenido)

list_notes

Lista todas las notas de un directorio (recursivo opcional).

¿Qué hay en 04-Tareas/?
→ list_notes("04-Tareas", recursive=True)

find_by_tag

Encuentra notas que contengan una etiqueta específica en su frontmatter.

¿Qué notas tienen el tag "pendiente"?
→ find_by_tag("pendiente")

get_backlinks

Devuelve todas las notas que enlazan a una nota concreta mediante [[wikilinks]].

¿Qué notas enlazan a r2d2.md?
→ get_backlinks("r2d2.md")

vault_structure

Devuelve el árbol de directorios del vault. Útil para que el asistente entienda la organización antes de buscar o escribir.

💬 Ejemplo de sesión real

Tú: Tengo que documentar lo que hice hoy en el servidor r2d2.
     Busca si ya tengo una nota de ese host.

Claude: [search_vault("r2d2")] → encontrada: 06-Janet/hypervisors/r2d2.md

Claude: [read_note("06-Janet/hypervisors/r2d2.md")] → leo el contenido actual

Claude: Aquí está tu nota de r2d2. ¿Quieres que añada una sección
        con la fecha de hoy y lo que me cuentes?

Tú: Sí, añade que amplié la RAM a 64GB y actualicé el kernel a 6.12.

Claude: [write_note("06-Janet/hypervisors/r2d2.md", contenido_actualizado)]
        Nota actualizada.

Todo sin salir del chat. Sin abrir Obsidian. Sin copiar nada a mano.

📚 La serie

• Parte 1 — Introducción y visión general
• [Parte 2 — harper-obsidian] ← estás aquí
• Parte 3 — harper-ssh: SSH y nmap sin salir de Claude
• Parte 4 — harper-winrm: administrar Windows desde Linux
• Parte 5 — harper-osint: investigación de fuentes abiertas

Repo: github.com/jaimealberto/harper-mcps