Obsidian

Interactúa con tu bóveda de Obsidian usando lenguaje natural.

Documentación

Obsidian MCP Server

Un potente servidor Model Context Protocol (MCP) para la interacción en lenguaje natural con tu bóveda de Obsidian. Construido con TypeScript y diseñado para una integración perfecta con Claude Code y otros clientes MCP.

Características

Capacidades principales

Consultas en lenguaje natural: Haz preguntas sobre tu bóveda en inglés sencillo
Búsqueda avanzada: Búsqueda inteligente con análisis de enlaces, jerarquías de etiquetas y contexto estructural
Análisis de enlaces inversos: Encuentra y analiza conexiones entre notas
Navegación en la bóveda: Explora la estructura de directorios y descubre notas
Operaciones CRUD completas: Leer, escribir, crear, añadir y actualizar notas

Herramientas avanzadas de inteligencia

Ruta de historia guiada: Genera recorridos narrativos a través de notas enlazadas
Auditoría de notas: Encuentra notas modificadas recientemente que carecen de frontmatter o estructura
Compañeros contextuales: Descubre notas relacionadas basadas en enlaces, palabras clave y actualidad
Energía fresca: Identifica notas actualizadas recientemente que necesitan integración
Puente de iniciativa: Realiza un seguimiento de notas específicas de proyectos con tareas pendientes
Eco de patrones: Encuentra notas que reutilizan frases o patrones específicos
Listo para síntesis: Detecta grupos de notas que necesitan notas de resumen

Instalación

Desde el código fuente

Clona el repositorio:

git clone https://github.com/dbmcco/obsidian-mcp.git
cd obsidian-mcp

Instala las dependencias:
```
npm install
```
Compila el proyecto:
```
npm run build
```

Configuración

Configuración para Claude Code

Añade a tu configuración MCP de Claude Code:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Configuración para Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Variables de entorno

OBSIDIAN_VAULT_PATH: Requerido. Ruta absoluta a tu bóveda de Obsidian

Herramientas disponibles

Operaciones básicas

query_vault

Procesa consultas en lenguaje natural sobre el contenido de tu bóveda.

Ejemplo: "¿Cuáles son los temas principales en mis notas de proyecto?"

{
  query: string,
  vaultPath?: string  // Optional override
}

search_notes

Busca notas por nombre de archivo o contenido mediante coincidencia exacta de texto.

{
  searchTerm: string,
  searchType: 'filename' | 'content' | 'both',  // Default: 'both'
  vaultPath?: string
}

intelligent_search

Búsqueda avanzada con análisis del grafo de enlaces, jerarquías de etiquetas y ponderación del contexto estructural.

{
  query: string,
  vaultPath?: string
}

list_directories

Explora la estructura de directorios de la bóveda con recuentos de notas.

{
  directoryPath?: string,  // Empty string for vault root
  vaultPath?: string
}

get_note

Recupera el contenido completo de una nota específica.

{
  notePath: string,  // Relative to vault root
  vaultPath?: string
}

get_backlinks

Encuentra todas las notas que enlazan a una nota específica con contexto.

{
  notePath: string,
  vaultPath?: string
}

Operaciones de escritura

write_note

Escribe o sobrescribe completamente una nota.

{
  notePath: string,
  content: string,
  vaultPath?: string
}

create_note

Crea una nueva nota con frontmatter y contenido.

{
  notePath: string,
  title: string,
  content?: string,
  tags?: string[],
  vaultPath?: string
}

append_to_note

Añade contenido a una nota existente.

{
  notePath: string,
  content: string,
  vaultPath?: string
}

update_note_section

Actualiza una sección específica identificada por su encabezado.

{
  notePath: string,
  sectionHeading: string,
  newContent: string,
  vaultPath?: string
}

Inteligencia avanzada

guided_path

Genera un recorrido narrativo a través de notas enlazadas a partir de una nota semilla.

{
  notePath: string,
  supportingLimit?: number,      // Default: 3
  counterpointLimit?: number,    // Default: 3
  includeActionItems?: boolean,  // Default: true
  vaultPath?: string
}

Salida: Narrativa en Markdown con introducción, hilos de apoyo, contrapuntos y elementos de acción.

audit_recent_notes

Encuentra notas modificadas recientemente que carecen de frontmatter o estructura.

{
  hoursBack?: number,           // Default: 72
  limit?: number,               // Default: 25
  requiredFields?: string[],    // Default: ['title', 'created']
  requireHeadings?: boolean,    // Default: false
  vaultPath?: string
}

contextual_companions

Descubre notas relacionadas con un tema o nota semilla según enlaces, palabras clave y actualidad.

{
  notePath?: string,    // Optional seed note
  topic?: string,       // Optional topic query
  limit?: number,       // Default: 5
  vaultPath?: string
}

Nota: Debe proporcionarse notePath o topic.

fresh_energy

Encuentra notas actualizadas recientemente que carecen de enlaces entrantes o salientes (necesitan integración).

{
  hoursBack?: number,   // Default: 48
  limit?: number,       // Default: 10
  minWords?: number,    // Default: 80
  vaultPath?: string
}

initiative_bridge

Realiza un seguimiento de notas etiquetadas como proyecto o iniciativa con tareas pendientes.

{
  initiative: string,           // Required: project identifier
  frontmatterField?: string,    // Default: 'project'
  limit?: number,               // Default: 10
  vaultPath?: string
}

pattern_echo

Encuentra notas que reutilizan frases específicas, patrones de viñetas o fragmentos de marcos.

{
  snippet: string,      // Required: text pattern to find
  limit?: number,       // Default: 5
  vaultPath?: string
}

synthesis_ready

Detecta grupos de notas interconectadas que carecen de una nota de resumen o síntesis.

{
  minClusterSize?: number,  // Default: 3
  vaultPath?: string
}

Ejemplos de casos de uso

Descubrimiento de conocimiento

// Find all notes about a topic with intelligent expansion
await intelligentSearch({ query: "machine learning" });

// Discover related notes for further reading
await contextualCompanions({
  topic: "neural networks",
  limit: 10
});

Mantenimiento de la bóveda

// Audit recent work for missing metadata
await auditRecentNotes({
  hoursBack: 168,  // Last week
  requiredFields: ['title', 'created', 'tags']
});

// Find orphaned notes needing links
await freshEnergy({ hoursBack: 72 });

// Identify note clusters needing synthesis
await synthesisReady({ minClusterSize: 4 });

Gestión de proyectos

// Track all tasks for a specific project
await initiativeBridge({
  initiative: "Project Alpha",
  frontmatterField: "project"
});

// Generate a narrative overview of a topic
await guidedPath({
  notePath: "Projects/Project Alpha.md",
  supportingLimit: 5,
  includeActionItems: true
});

Análisis de patrones

// Find notes using a specific framework
await patternEcho({
  snippet: "SWOT Analysis:",
  limit: 10
});

Desarrollo

Scripts

npm run dev: Modo de observación para desarrollo
npm run build: Compila TypeScript a JavaScript
npm run start: Inicia el servidor MCP

Estructura del proyecto

obsidian-mcp/
├── src/
│   ├── index.ts           # MCP server and tool definitions
│   ├── vault-manager.ts   # Vault operations and intelligence
│   └── query-processor.ts # Natural language query processing
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Detalles técnicos

Arquitectura

TypeScript con modo estricto habilitado
Módulos ES (NodeNext)
Zod para validación de tipos en tiempo de ejecución
gray-matter para el análisis de frontmatter
glob para la coincidencia de patrones de archivos

Métodos de búsqueda

La herramienta intelligent_search combina cuatro estrategias de búsqueda:

Coincidencia directa: coincidencias exactas de palabras clave en contenido/nombres de archivo
Proximidad de enlaces: notas conectadas mediante enlaces wiki
Expansión de etiquetas: notas relacionadas mediante jerarquías de etiquetas
Contexto estructural: búsqueda con reconocimiento de secciones y puntuación de relevancia

Los resultados se fusionan, deduplican y clasifican por puntuación de relevancia.

Rendimiento

Sin caché: todas las búsquedas son en tiempo real para evitar datos obsoletos
Carga diferida del contenido de notas para bóvedas grandes
Patrones glob eficientes para el descubrimiento de archivos

Créditos

Construido por Braydon con Claude (Anthropic). Este servidor MCP se desarrolló siguiendo principios de desarrollo guiado por pruebas y una colaboración exhaustiva con Claude Code.

Licencia

Licencia MIT: siéntete libre de usar y modificar según sea necesario.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Haz un fork del repositorio
Crea una rama de funcionalidad
Realiza tus cambios con pruebas
Envía una solicitud de extracción

Solución de problemas

Error "No se proporcionó ruta de bóveda"

Asegúrate de que OBSIDIAN_VAULT_PATH esté configurado en tu configuración MCP o en las variables de entorno.

El servidor MCP no se conecta

Verifica que la ruta a dist/index.js sea absoluta, no relativa
Asegúrate de que el servidor esté compilado (npm run build)
Comprueba que Node.js pueda ejecutar el script

La búsqueda no devuelve resultados

Verifica que la ruta de la bóveda sea correcta
Comprueba que existan archivos .md en la bóveda
Intenta usar list_directories para explorar la estructura de la bóveda