Servidor MCP de Obsidian

obsidian-mcp-server es un servidor MCP que permite a los agentes de IA consultar, buscar y resumir documentos Markdown de un Vault de Obsidian.

Al conectarse a un cliente MCP, permite a los agentes consultar el contenido del Vault controlando el uso de tokens.

¿Qué puede hacer?

• Búsqueda de notas basada en palabras clave (vault, action="search")

• Lectura de notas específicas (vault, action="read")

• Listado de todos los documentos del Vault (vault, action="list_all")

• Consulta del estado del Vault (vault, action="stats")

• Creación de paquetes de memoria para contexto a largo plazo (vault, action="collect_context")

• Carga de notas de memoria guardadas (vault, action="load_memory")

• Sugerencias de generación automática de frontmatter (generate_property)

• Aplicación real de frontmatter (write_property)

• Flujos de trabajo de prompts basados en documentos (create_document_with_properties)

• Organización de archivos adjuntos de imágenes (organize_attachments)

Precauciones previas

Este servidor expone el contenido del Vault al cliente. Úselo con precaución en entornos de producción.

• No se conecte a agentes de IA en los que no confíe.

• Limite la ruta del Vault (VAULT_DIR_PATH) con privilegios mínimos.

• Para Vaults con gran volumen de consultas, ajuste maxOutputChars y limit para controlar los costos de tokens.

• El modo de compresión predeterminado para la acción vault es balanced.

Verificaciones de configuración

1. Ruta del Vault: Debe ingresar la ruta absoluta en VAULT_DIR_PATH.

// ✅ 올바른 예시
"VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
"VAULT_DIR_PATH": "C:\\Users\\username\\Documents\\MyVault"  // Windows
"VAULT_DIR_PATH": "/mnt/c/Users/username/Documents/MyVault"  // WSL

// ❌ 잘못된 예시
"VAULT_DIR_PATH": "~/Documents/MyVault"  // 상대 경로 사용 불가
"VAULT_DIR_PATH": "./vault"              // 상대 경로 사용 불가

2. Requisitos de Node.js: Debe tener instalado Node.js 22 o superior.

node --version  # v22.0.0 이상 확인

Introducción (Configuración rápida)

1) Requisitos comunes

• La configuración mínima es VAULT_DIR_PATH (ruta absoluta del Vault).

• La ejecución de MCP se explica basada en el paquete de distribución.

  • Uso del paquete de distribución (npx) (recomendado)

  • El archivo local build/index.js es para fines de desarrollo/depuración.

• La ejecución local se detalla en la última sección (5).

• Si no hay una ruta de Vault, el inicio fallará.

• Los ejemplos a continuación están organizados para copiar y pegar directamente.

2) Configuración del paquete de distribución (npx)

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": {
        "VAULT_DIR_PATH": "/abs/path/to/your/vault",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

Ejecución directa por CLI:

npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault --logging-level info

3) Configuración del cliente MCP

Aunque la interfaz de usuario varía según el cliente, la forma básica de command/args/env es la misma.

Clave basada en el paquete de distribución: command="npx", args=["-y","@sunub/obsidian-mcp-server@latest"], env.VAULT_DIR_PATH

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "@sunub/obsidian-mcp-server@latest"]
env = { VAULT_DIR_PATH = "/abs/path/to/your/vault" }

1. Ejecute copilot

2. /mcp add

3. Ingrese los siguientes valores:

• Server name: obsidian

• Server Type: [1] Local

• Command: npx -y @sunub/obsidian-mcp-server@latest

• Environment: { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }

Dado que los nombres de las claves JSON pueden variar según la versión (ej. servers/mcpServers), aplíquelo según la documentación de su proyecto.

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
    }
  }
}

Regístrelo en Cursor Settings → MCP → New MCP Server.

{
  "obsidian": {
    "command": "npx",
    "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
    "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
  }
}

※ Algunas versiones pueden tener nombres de clave de servidor diferentes, así que siga las instrucciones de la pantalla de configuración.

Ejemplo de instalación de paquete:

gemini mcp add obsidian npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault

※ Algunas versiones de Gemini pueden tener un soporte diferente para --vault-path, así que consulte la documentación más reciente de gemini mcp add.

4) Ejemplo de configuración completa

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "@sunub/obsidian-mcp-server@latest"
      ],
      "env": {
        "VAULT_DIR_PATH": "/path/to/obsidian-vault",
        "VAULT_METRICS_LOG_PATH": "/path/to/vault-metrics.ndjson",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

Configuración de variables de entorno

• VAULT_DIR_PATH (obligatorio): Ruta absoluta del Vault de Obsidian

• VAULT_METRICS_LOG_PATH (opcional): Registra las métricas de compresión/tokens de respuesta en formato JSONL

• LOGGING_LEVEL (opcional): debug | info | warn | error

Verificación rápida tras el inicio

Una vez finalizada la conexión, verifique primero estos 3 puntos: Incluso si no se abren los documentos, podrá identificar rápidamente dónde falló.

1. Verificar el estado del Vault

"Vault 상태를 요약해줘."

Comportamiento interno esperado:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": { "action": "stats" }
  }
}

En caso de funcionamiento normal, la respuesta incluirá totalFiles, isInitialized y vaultPath.

2. Verificar el índice de búsqueda

"노트 제목에 'MCP'가 들어간 문서만 5개 찾아줘."

Comportamiento interno esperado:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "search",
      "keyword": "MCP",
      "limit": 5
    }
  }
}

Si el resultado de search está vacío, sospeche de la indexación, la ruta o el rango de palabras clave.

3. Verificar la lectura de documentos

"특정 노트 하나를 읽어줘."

Comportamiento interno esperado:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "read",
      "filename": "예: 어떤 문서 이름"
    }
  }
}

Si el filename es incorrecto, recibirá { "error": "Document not found: ..." }. Es más rápido verificar primero los candidatos con list_all en lugar de read.

search, list_all y load_memory tienen quiet configurado como true por defecto, por lo que la respuesta básica puede ser breve. Si es necesario, use quiet: false, includeContent: true y excerptLength (o maxOutputChars) para obtener detalles.

Ejemplos de uso

Es más importante "qué acción se intenta realizar" que cómo se llama al MCP.

Ejemplo de acción para organizar archivos adjuntos escritos en un documento Markdown:

https://github.com/user-attachments/assets/eb74ec05-09f7-4632-a22c-666b7e844147

• Si solicita organizar los archivos adjuntos de imágenes escritos en un documento específico, creará una carpeta con el nombre del archivo dentro de la carpeta images y los organizará allí.

• El documento organizado actualizará sus enlaces basándose en la carpeta images para que no se rompan las conexiones existentes.

Ejemplos de preguntas para ejecución directa:

• "Busca solo la parte de MCP Client configuration en 시작하기 (빠른 설정) dentro de README.md."

• "Lee y resume solo el ejemplo de configuración de vault en docs/tools-usage-guide.md."

• "Busca solo el parámetro collect_context de vault en docs/tool-reference.md."

• "Resume solo el bloque de configuración del MCP 서버 en docs/tools-usage-guide.md."

Los ejemplos en lenguaje natural funcionan con mayor precisión si se escriben de forma específica, como se muestra a continuación:

• "README.md의 시작하기 부분에서 실행 명령 예시만 찾아줘" (Busca solo los ejemplos de comandos de ejecución en la sección de inicio de README.md)

• "docs/tools-usage-guide.md에서 vault 관련 사용 예시만 찾아서 비교해줘" (Busca y compara solo los ejemplos de uso relacionados con vault en docs/tools-usage-guide.md)

• "docs/tool-reference.md의 vault.read 파라미터 설명만 읽어줘" (Lee solo la descripción del parámetro vault.read en docs/tool-reference.md)

vault se llama internamente basándose en la pregunta del usuario, y el flujo real funciona de la siguiente manera:

• "README.md의 시작하기 (빠른 설정)에서 npx 예시만 보여줘" (Muéstrame solo el ejemplo de npx en la configuración rápida de README.md) → Se extraen las palabras clave principales y se llama primero a vault.search.

• "docs/tool-reference.md의 collect_context 파라미터만 읽어줘" (Lee solo el parámetro collect_context de docs/tool-reference.md) → Primero se lee la parte correspondiente del documento con vault.read y, si es necesario, se organiza con vault.collect_context.

• "docs/tools-usage-guide.md에서 frontmatter 처리 과정을 읽어줘" (Lee el proceso de manejo de frontmatter en docs/tools-usage-guide.md) → Después de encontrar la ubicación del documento con vault.read, se pueden llamar secuencialmente generate_property/write_property/create_document_with_properties.

Consulte el flujo de llamadas de las herramientas en Ejemplos de uso (flujo de llamadas de herramientas) junto con ejemplos JSON concretos.

Herramientas registradas

• Obsidian Tools (6 actions)

  • vault

    • search

    • read

    • list_all

    • stats

    • collect_context

    • load_memory

• generate_property

• write_property

• create_document_with_properties

• organize_attachments

Normas de uso detalladas

• Consulte Tool Reference para conocer el funcionamiento detallado de las herramientas, los valores predeterminados de los parámetros y el formato de respuesta real.

• vault es una única herramienta MCP y la acción real se deriva del valor action. Los errores tipográficos son la causa más común de fallo.

• En Vaults a gran escala, comience con collect_context usando scope="all" y un maxDocs pequeño, y expanda gradualmente.