Obsidian MCP Server - Enhanced

Proporciona acceso completo a una bóveda de Obsidian, permitiendo a los agentes de IA leer, escribir, buscar y gestionar notas a través del plugin Local REST API.

GitHub

Prueba este MCPPatrocinado

Documentación

Obsidian MCP Server - Enhanced

Servidor MCP de Obsidian Mejorado con Integración Remota de Claude.ai, Soporte de Tailscale y Capacidades Avanzadas de Consulta.

🔥 Aviso de Bifurcación Mejorada: Esta es una versión mejorada del excelente cyanheads/obsidian-mcp-server con características adicionales específicamente diseñadas para la integración remota de Claude.ai, consulta avanzada de tareas y seguridad mediante Tailscale.

Un servidor MCP (Protocolo de Contexto de Modelo) que proporciona acceso integral a tu bóveda de Obsidian. Permite que los LLM y agentes de IA lean, escriban, busquen y gestionen tus notas y archivos a través del plugin Obsidian Local REST API.

Construido sobre el cyanheads/mcp-ts-template, este servidor sigue una arquitectura modular con manejo robusto de errores, registro de actividades y características de seguridad.

🚀 Características Mejoradas (Esta Bifurcación)

🏛️ Soporte Multi-Bóveda

Acceso simultáneo a múltiples bóvedas de Obsidian a través de un único servidor MCP:

Gestión de Múltiples Bóvedas: Conéctate a múltiples instancias de Obsidian en diferentes puertos simultáneamente
Enrutamiento Específico por Bóveda: Las herramientas se enrutan automáticamente a la bóveda correcta según el parámetro vault
Autenticación Individual: Claves API separadas para cada bóveda con autenticación MCP centralizada
Compatibilidad Retroactiva: Las configuraciones existentes de bóveda única continúan funcionando sin cambios
Configuración Dinámica: Configuración de bóvedas basada en JSON con validación y manejo de errores

🌐 Integración Remota con Claude.ai

Integración perfecta con la función MCP Remota de Claude.ai:

Modo HTTP Sin Estado: Transporte dedicado sin estado para compatibilidad con Claude.ai (MCP_HTTP_STATELESS=true)
Modo Basado en Sesiones: Gestión tradicional de sesiones para otros clientes MCP
Autenticación Simplificada: Utiliza una clave MCP_AUTH_KEY dedicada para el acceso al servidor
Configuración Cero: Funciona de inmediato con servidores MCP remotos de Claude.ai
Listo para Producción: Estabilidad y manejo de errores de nivel empresarial

🔒 Acceso Remoto Seguro con Tailscale

Accede a tu bóveda de Obsidian de forma segura desde cualquier lugar:

Integración con Tailscale Funnel: Endpoints HTTPS seguros con certificados automáticos
Cifrado de Extremo a Extremo: Todo el tráfico cifrado a través de la red Tailscale
Sin Redirección de Puertos: No se requiere configuración de red
Control de Acceso: Soporte integrado de ACL de Tailscale para seguridad empresarial

📊 Sistema Mejorado de Tareas y Consultas

Capacidades de consulta avanzadas más allá del original:

Integración con el Plugin de Tareas: Integración profunda con el plugin Obsidian Tasks
Análisis Avanzado de Fechas: Reconocimiento de fechas en lenguaje natural
Detección de Prioridades: Análisis de prioridades visual y basado en texto
Múltiples Formatos de Salida: Vistas de tabla, lista y resumen

🔧 Monitoreo de Producción y Fiabilidad

Capacidades de monitoreo y reinicio automático de nivel empresarial:

Script de Verificación de Salud: Validación integral de componentes (scripts/health-check.sh)
Monitoreo Inteligente: Reinicio automático con gestión del ciclo de vida de procesos (scripts/monitor-mcp.sh)
Inicio Automático en macOS: Configuración del agente de lanzamiento para el inicio del sistema (scripts/setup-autostart.sh)
Gestión Dinámica de Puertos: Resolución automática de conflictos de puertos (rango 3010-3013)
Registro Mejorado: Depuración detallada de conexiones y validación de claves API

🚀 Capacidades Principales: Herramientas de Obsidian 🛠️

Este servidor equipa a tu IA con herramientas especializadas para interactuar con tu bóveda de Obsidian:

Nombre de la Herramienta	Descripción	Características Clave
`obsidian_read_file`	Recupera el contenido y los metadatos de un archivo específico.	- Lectura en formato `markdown` o `json`. - Respaldo de ruta sin distinción de mayúsculas. - Incluye estadísticas del archivo (tiempo de creación/modificación).
`obsidian_update_file`	Modifica notas mediante operaciones de archivo completo.	- Contenido `append`, `prepend` o `overwrite`. - Puede crear archivos si no existen. - Apunta a archivos por ruta, nota activa o nota periódica.
`obsidian_search_replace`	Realiza operaciones de buscar y reemplazar dentro de una nota objetivo.	- Soporta búsqueda de cadenas o expresiones regulares. - Opciones para sensibilidad a mayúsculas, palabra completa y reemplazo de todas las ocurrencias.
`obsidian_global_search`	Realiza una búsqueda en toda la bóveda.	- Búsqueda de texto o expresiones regulares. - Filtro por ruta y fecha de modificación. - Resultados paginados.
`obsidian_list_files`	Lista archivos y subdirectorios dentro de una carpeta de la bóveda especificada.	- Filtro por extensión de archivo o expresión regular de nombre. - Proporciona una vista de árbol formateada del directorio.
`obsidian_manage_frontmatter`	Gestiona atómicamente el frontmatter YAML de una nota.	- Claves de frontmatter `get`, `set` o `delete`. - Evita reescribir todo el archivo para cambios de metadatos.
`obsidian_manage_tags`	Agrega, elimina o lista etiquetas para una nota.	- Gestiona etiquetas tanto en el frontmatter YAML como en el contenido en línea.
`obsidian_delete_file`	Elimina permanentemente un archivo especificado de la bóveda.	- Respaldo de ruta sin distinción de mayúsculas por seguridad.
`obsidian_dataview_query`	Ejecuta consultas DQL de Dataview contra tu bóveda.	- Ejecuta consultas TABLE, LIST usando sintaxis de Dataview. - Consulta notas por etiquetas, frontmatter, fechas. - Genera informes y análisis.
`obsidian_task_query`	Busca y analiza tareas en toda tu bóveda.	- Filtro por estado, rangos de fechas, prioridades. - Múltiples formatos de salida. - Extrae metadatos de tareas (fechas de vencimiento, etiquetas).

Tabla de Contenidos

Descripción General

El Servidor MCP de Obsidian actúa como un puente, permitiendo que las aplicaciones (Clientes MCP) que entienden el Protocolo de Contexto de Modelo (MCP) – como asistentes de IA avanzados (LLM), extensiones de IDE o scripts personalizados – interactúen directa y seguramente con tu bóveda de Obsidian.

En lugar de scripts complejos o interacción manual, tus herramientas pueden aprovechar este servidor para:

Automatizar la gestión de la bóveda: Leer notas, actualizar contenido, gestionar frontmatter y etiquetas, buscar entre archivos, listar directorios y eliminar archivos programáticamente.
Integrar Obsidian en flujos de trabajo de IA: Permitir que los LLM accedan y modifiquen tu base de conocimiento como parte de sus tareas de investigación, escritura o codificación.
Construir herramientas personalizadas de Obsidian: Crear aplicaciones externas que interactúen con los datos de tu bóveda de formas novedosas.

Construido sobre el robusto mcp-ts-template, este servidor proporciona una forma estandarizada, segura y eficiente de exponer la funcionalidad de Obsidian a través del estándar MCP. Logra esto comunicándose con el potente plugin Obsidian Local REST API que se ejecuta dentro de tu bóveda.

Nota para Desarrolladores: Este repositorio incluye un archivo .clinerules que sirve como una hoja de referencia para tu agente de codificación LLM con referencia rápida a los patrones del código base, ubicaciones de archivos y fragmentos de código.

Características

Utilidades Principales

Aprovecha las robustas utilidades proporcionadas por el mcp-ts-template:

Registro de Actividades: Registro estructurado y configurable (rotación de archivos, consola, notificaciones MCP) con redacción de datos sensibles.
Manejo de Errores: Procesamiento centralizado de errores, tipos de error estandarizados (McpError) y registro automático.
Configuración: Carga de variables de entorno (dotenv) con validación integral.
Validación/Saneamiento de Entrada: Utiliza zod para la validación de esquemas y lógica de saneamiento personalizada.
Contexto de Solicitud: Seguimiento y correlación de operaciones mediante ID de solicitud únicos.
Seguridad de Tipos: Tipado fuerte impuesto por TypeScript y esquemas Zod.
Opción de Transporte HTTP: Servidor HTTP nativo de Node.js con gestión de sesiones, soporte CORS y autenticación mediante clave API.

Integración con Obsidian

Integración con Obsidian Local REST API: Se comunica directamente con el plugin Obsidian Local REST API mediante solicitudes HTTP gestionadas por el ObsidianRestApiService.
Cobertura Integral de Comandos: Expone operaciones clave de la bóveda como herramientas MCP (ver sección Herramientas).
Interacción con la Bóveda: Soporta lectura, actualización (añadir, anteponer, sobrescribir), búsqueda (texto global/expresiones regulares, buscar y reemplazar), listado, eliminación y gestión de frontmatter y etiquetas.
Flexibilidad de Destino: Las herramientas pueden apuntar a archivos por ruta, al archivo actualmente activo en Obsidian o a notas periódicas (diarias, semanales, etc.).
Servicio de Caché de Bóveda: Una caché inteligente en memoria que mejora el rendimiento y la resiliencia. Almacena en caché el contenido de la bóveda, proporciona un respaldo para la herramienta de búsqueda global si la API en vivo falla y se actualiza periódicamente para mantenerse sincronizada.
Características de Seguridad: Respaldos de ruta sin distinción de mayúsculas para operaciones de archivos, distinción clara entre tipos de modificación (añadir, sobrescribir, etc.).

Instalación

Requisitos Previos

Obsidian: Necesitas tener Obsidian instalado.
Plugin Obsidian Local REST API: Instala y habilita el plugin Obsidian Local REST API dentro de tu bóveda de Obsidian.
Clave API: Configura una clave API dentro de la configuración del plugin Local REST API en Obsidian. Necesitarás esta clave para configurar el servidor.
Node.js y npm: Asegúrate de tener Node.js (se recomienda v18 o posterior) y npm instalados.
Tailscale (para acceso remoto): Instala Tailscale y habilita Tailscale Funnel para la integración remota segura con Claude.ai.

💡 Configuración Rápida: Para el inicio automático al arrancar, consulta la Guía de Configuración de Inicio Automático después de la instalación.

Instalación

Clona este repositorio mejorado:

git clone https://github.com/BoweyLou/obsidian-mcp-server-enhanced.git
cd obsidian-mcp-server-enhanced

Instala las dependencias:
```
npm install
```
Compila el proyecto:
```
npm run build
```
Esto compila el código TypeScript a JavaScript en el directorio dist/ y hace ejecutable el punto de entrada.

Configuración

Variables de Entorno

Configura el servidor usando variables de entorno.

Estas variables deben establecerse en la configuración del cliente MCP (por ejemplo, cline_mcp_settings.json) o en tu entorno antes de iniciar el servidor (si se ejecuta directamente). Si se ejecuta directamente, se pueden configurar en un archivo .env en la raíz del proyecto o directamente en su entorno.

Variable	Descripción	Requerido	Predeterminado
`MCP_AUTH_KEY`	Clave de autenticación para acceso remoto a MCP de Claude.ai. Genérela con `openssl rand -hex 32`	Sí (Remoto)	`undefined`
`OBSIDIAN_VAULTS`	Matriz JSON de configuraciones de bóvedas para el modo multi-bóveda.	Sí (Múltiple)	`undefined`
`OBSIDIAN_API_KEY`	Clave API del plugin de Obsidian (solo modo de bóveda única).	Sí (Única)	`undefined`
`OBSIDIAN_BASE_URL`	URL base de la API de Obsidian (solo modo de bóveda única).	Sí (Única)	`http://127.0.0.1:27123`
`MCP_TRANSPORT_TYPE`	Transporte del servidor: `stdio` o `http`.	No	`http`
`MCP_HTTP_PORT`	Puerto para el servidor HTTP.	No	`3010`
`MCP_HTTP_HOST`	Host para el servidor HTTP.	No	`127.0.0.1`
`MCP_HTTP_STATELESS`	Habilite el modo sin estado para compatibilidad con Claude.ai.	No	`false`
`MCP_ALLOWED_ORIGINS`	Orígenes separados por comas para CORS. Configúrelo para producción.	No	(ninguno)
`CHATGPT_LAYER_ENABLED`	Establézcalo en `true` para servir el manifiesto de ChatGPT más el endpoint de acciones JSON.	No	`false`
`CHATGPT_MANIFEST_PATH`	Ruta HTTP que expone el JSON del manifiesto de ChatGPT.	No	`/.well-known/obsidian-chatgpt-manifest.json`
`CHATGPT_ACTIONS_PATH`	Ruta HTTP para acciones JSON de ChatGPT (POST).	No	`/chatgpt/actions`
`CHATGPT_FACADE_TOKEN_TTL_SECONDS`	Duración del token de acceso de la fachada de ChatGPT.	No	`3600`
`CHATGPT_FACADE_REFRESH_TOKEN_TTL_SECONDS`	Duración del token de actualización de la fachada de ChatGPT.	No	`2592000`
`CHATGPT_FACADE_SCOPES`	Ámbitos de la fachada de ChatGPT separados por comas. Agregue ámbitos de escritura solo para clientes explícitamente confiables.	No	`obsidian:read`
`MCP_LOG_LEVEL`	Nivel de registro (`debug`, `info`, `error`, etc.).	No	`info`
`OBSIDIAN_VERIFY_SSL`	Establézcalo en `false` para deshabilitar la verificación SSL.	No	`true`
`OBSIDIAN_ENABLE_CACHE`	Establézcalo en `true` para habilitar la caché de bóveda en memoria.	No	`true`
`OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN`	Intervalo de actualización de la caché de bóveda en minutos.	No	`10`

Configuración Multi-Bóveda

El servidor admite tanto el modo de bóveda única (compatible con versiones anteriores) como el modo multi-bóveda:

Modo de Bóveda Única (Legado)

# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_API_KEY=your-obsidian-plugin-api-key
OBSIDIAN_BASE_URL=http://127.0.0.1:27123
MCP_TRANSPORT_TYPE=http
MCP_HTTP_STATELESS=true

Modo Multi-Bóveda (Recomendado)

# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_VAULTS='[
  {
    "id": "work",
    "name": "Work Vault", 
    "apiKey": "work-vault-api-key",
    "baseUrl": "http://127.0.0.1:27123",
    "verifySsl": false
  },
  {
    "id": "personal",
    "name": "Personal Vault",
    "apiKey": "personal-vault-api-key", 
    "baseUrl": "http://127.0.0.1:27122",
    "verifySsl": false
  }
]'
MCP_TRANSPORT_TYPE=http
MCP_HTTP_STATELESS=true

Proceso de Configuración

Generar clave de autenticación MCP: openssl rand -hex 32
Configurar múltiples instancias de Obsidian: Instale el plugin Local REST API en diferentes puertos
Obtener claves API: Extraiga las claves API de la configuración del plugin de cada instancia de Obsidian
Configurar bóvedas: Actualice .env con la configuración JSON OBSIDIAN_VAULTS
Iniciar servidor: npm run start:http
Acceso a través de Claude.ai: Use su URL de Tailscale con MCP_AUTH_KEY

Conexión a la API de Obsidian

Modo de Bóveda Única

Para conectarse en modo de bóveda única, configure la URL base (OBSIDIAN_BASE_URL) y la clave API (OBSIDIAN_API_KEY). El plugin Local REST API de Obsidian ofrece dos tipos de conexión:

Cifrado (HTTPS):
- Usa el endpoint seguro https:// (p. ej., https://127.0.0.1:27124)
- Requiere OBSIDIAN_VERIFY_SSL=false para certificados autofirmados
No cifrado (HTTP) - Recomendado:
- Usa el endpoint http:// (p. ej., http://127.0.0.1:27123)
- Configuración más simple, no se necesita verificación SSL

Modo Multi-Bóveda

Para el modo multi-bóveda, configure cada bóveda individualmente en la matriz JSON OBSIDIAN_VAULTS con su propia clave API y URL base. Cada bóveda puede usar HTTP o HTTPS según sea necesario.

Ejemplos de configuración:

Bóveda única con HTTP:

"env": {
  "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
  "OBSIDIAN_API_KEY": "your-obsidian-api-key",
  "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
}

Configuración multi-bóveda:

"env": {
  "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
  "OBSIDIAN_VAULTS": "[{\"id\":\"work\",\"name\":\"Work\",\"apiKey\":\"work-key\",\"baseUrl\":\"http://127.0.0.1:27123\"},{\"id\":\"personal\",\"name\":\"Personal\",\"apiKey\":\"personal-key\",\"baseUrl\":\"http://127.0.0.1:27122\"}]"
}

Configuración del Cliente MCP Local (Opcional)

Nota: Para la integración remota de MCP con Claude.ai, omita esta sección y use la Configuración de Acceso Remoto con Tailscale en su lugar.

Para clientes MCP locales (p. ej., Cline), agregue a su configuración (p. ej., cline_mcp_settings.json):

Configuración de bóveda única:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server-enhanced/dist/index.js"],
      "env": {
        "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
        "OBSIDIAN_API_KEY": "your-obsidian-api-key",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

Configuración multi-bóveda:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server-enhanced/dist/index.js"],
      "env": {
        "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
        "OBSIDIAN_VAULTS": "[{\"id\":\"work\",\"name\":\"Work Vault\",\"apiKey\":\"work-api-key\",\"baseUrl\":\"http://127.0.0.1:27123\"},{\"id\":\"personal\",\"name\":\"Personal Vault\",\"apiKey\":\"personal-api-key\",\"baseUrl\":\"http://127.0.0.1:27122\"}]",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

🌐 Configuración de Acceso Remoto (Tailscale)

Para acceso remoto a su bóveda de Obsidian desde cualquier lugar, puede usar Tailscale para exponer de forma segura su servidor MCP a través de internet.

Requisitos Previos

Cuenta de Tailscale: Regístrese en tailscale.com
Tailscale instalado: Instale Tailscale en su máquina que ejecuta el servidor MCP
Tailscale Funnel habilitado: Habilite Tailscale Funnel para su cuenta

Pasos de Configuración

Generar clave de autenticación MCP:
```
openssl rand -hex 32
```

Configurar el entorno: Configure su archivo .env con la clave generada:

MCP_AUTH_KEY=your-generated-auth-key
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_HTTP_STATELESS=true

Configurar bóvedas: Configure la bóveda única o multi-bóveda (consulte Configuración Multi-Bóveda)
Iniciar el servidor MCP:
```
npm run build && npm run start:http
```
Habilitar Tailscale Funnel:
```
tailscale funnel 3010
```
Obtener su URL pública: Verifique la URL de su dispositivo Tailscale:
```
tailscale status --self | grep "Funnel on"
```

Configuración Remota de MCP en Claude.ai

Agregue a sus servidores MCP remotos de Claude.ai usando su clave de autenticación MCP:

Configuración de bóveda única:

{
  "url": "https://your-device.your-tailnet.ts.net/mcp?api_key=your-mcp-auth-key",
  "name": "Obsidian Vault"
}

Configuración multi-bóveda:

{
  "url": "https://your-device.your-tailnet.ts.net/mcp?api_key=your-mcp-auth-key",
  "name": "Obsidian Multi-Vault"
}

Nota de autenticación: Claude.ai Remote MCP usa el MCP_AUTH_KEY para la autenticación del servidor. Las operaciones individuales de bóveda usan las claves API específicas de la bóveda configuradas en su entorno.

Consideraciones de Seguridad

Autenticación dual: Autenticación del servidor MCP mediante MCP_AUTH_KEY, autenticación de bóveda mediante claves API individuales
Cifrado de Tailscale: Todo el tráfico está cifrado de extremo a extremo por Tailscale
Red privada: Solo usted puede acceder al servidor a través de su red Tailscale
SSL automático: Tailscale Funnel proporciona certificados HTTPS automáticos
Aislamiento de bóvedas: Cada bóveda usa su propia clave API para un control de acceso seguro

Ejemplo de Uso

Una vez configurado, puede usar las herramientas de forma remota desde Claude.ai:

Comandos de bóveda única (usa la bóveda predeterminada):

Use obsidian_task_query to show me tasks due today with format="table"

Comandos multi-bóveda (especifique la bóveda):

Use obsidian_task_query with vault="work" to show me work tasks due today

Use obsidian_read_file with filePath="daily-note.md" and vault="personal"

Use obsidian_dataview_query with vault="work" to run: TABLE file.name FROM #meeting WHERE file.cday = date(today)

🚀 Consejo profesional: Para uso en producción, configure el inicio automático al arrancar para que su servidor y Tailscale Funnel se inicien automáticamente sin intervención manual.

Fachada del Conector ChatGPT

Claude y los clientes MCP locales pueden conectarse directamente a /mcp. Los conectores de ChatGPT alojados deben usar la fachada separada obsidian-chatgpt en su lugar. La fachada reutiliza la lógica existente de bóveda, búsqueda y tareas internamente, pero tiene su propio proceso, puerto, flujo de autorización OAuth/PKCE, capacidades con ámbito y registro de auditoría de escritura.

Use la fachada para rutas HTTPS públicas o de Tailscale Funnel. Mantenga el servidor MCP completo en localhost o en rutas privadas solo de tailnet, a menos que esté realizando una prueba local/de desarrollo explícita.

Inicio de la Fachada

Configure una URL de recurso pública y un secreto de aprobación de administrador, luego inicie la fachada:

export CHATGPT_FACADE_PUBLIC_URL="https://your-device.your-tailnet.ts.net"
export CHATGPT_FACADE_ADMIN_SECRET="$(openssl rand -hex 24)"
npm run build
npm run start:chatgpt

Si el mismo hostname de Funnel también expone otro conector de ChatGPT, asigne a esta fachada una URL de recurso con ámbito de ruta, como https://your-device.your-tailnet.ts.net/obsidian, y enrute el prefijo /obsidian al puerto de la fachada. La fachada sirve tanto las rutas de metadatos well-known de raíz como las calificadas por ruta para esa configuración. En esa configuración de host compartido, cree el conector con https://your-device.your-tailnet.ts.net/obsidian/mcp.

Verifique el estado:

curl "http://127.0.0.1:3020/health"

Para pruebas de superficie HTTP de la fachada sin una API de Obsidian activa, establezca CHATGPT_FACADE_SKIP_OBSIDIAN_CHECK=true. Déjelo sin establecer para el funcionamiento normal.

Exponga solo la fachada a través de Funnel:

make tailscale-funnel-chatgpt

OAuth y Ámbitos

La fachada publica metadatos de descubrimiento OAuth:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/.well-known/openid-configuration

Almacena localmente los hashes de código de autorización, token de acceso y token de actualización en CHATGPT_FACADE_STORE_PATH, no los tokens sin procesar. Requiere PKCE S256 para el intercambio inicial de tokens, admite la rotación de tokens de actualización y valida los tokens de portador por recurso, vencimiento y ámbito antes de ejecutar acciones.

Ámbitos:

obsidian:read: search, fetch, task_query, latest_note
obsidian:write: create_task, update_task, append_note, create_note, create_daily_note
obsidian:dangerous-write: overwrite_note

La configuración del conector de solo lectura es la predeterminada y se admite otorgando solo obsidian:read. overwrite_note no está disponible a menos que obsidian:dangerous-write se otorgue explícitamente.

Acciones de la Fachada

Todas las acciones usan POST /chatgpt/actions con Authorization: Bearer <token>. Aceptan un campo opcional vault. La superficie pública predeterminada es intencionalmente más pequeña que el conjunto completo de herramientas MCP locales.

Acción	Ámbito	Descripción
`search`	`obsidian:read`	Búsqueda global acotada con fragmentos.
`fetch`	`obsidian:read`	Obtener contenido de nota acotado por ruta de bóveda.
`task_query`	`obsidian:read`	Consulta de tareas compatible con el plugin Tasks.
`latest_note`	`obsidian:read`	Obtener la nota modificada más reciente, opcionalmente acotada por ruta.
`create_task`	`obsidian:write`	Crear una tarea compatible con el plugin Tasks.
`update_task`	`obsidian:write`	Actualizar una tarea existente.
`append_note`	`obsidian:write`	Agregar o anteponer contenido de nota.
`create_note`	`obsidian:write`	Crear una nota sin sobrescribir contenido existente.
`create_daily_note`	`obsidian:write`	Crear la nota diaria de hoy o una especificada a partir de la plantilla de nota diaria.
`overwrite_note`	`obsidian:dangerous-write`	Sobrescritura completa de nota para clientes explícitamente confiables.

Las respuestas exitosas de acciones usan el mismo envoltorio para acciones HTTP y llamadas de herramientas MCP de la fachada:

{
  "success": true,
  "action": "create_daily_note",
  "vault": "default",
  "resultPath": "Daily/2026-07-03.md",
  "data": {
    "filePath": "Daily/2026-07-03.md"
  }
}

Las acciones de escritura incluyen resultPath cuando se conoce la ruta de bóveda afectada. Las acciones de creación y actualización de tareas también incluyen taskLineNumber cuando el número de línea está disponible.

Las escrituras se agregan al registro de auditoría JSONL local en CHATGPT_FACADE_AUDIT_PATH. La entrada de auditoría registra acción, id de cliente, ámbitos, ruta de destino, modo, ruta de resultado, estado y un resumen de entrada limitado; no almacena transcripciones sin procesar de ChatGPT ni cuerpos completos de notas. Los operadores pueden inspeccionar las entradas recientes con:

curl "http://127.0.0.1:3020/audit/recent?admin_secret=$CHATGPT_FACADE_ADMIN_SECRET"

Capa Heredada en Proceso

CHATGPT_LAYER_ENABLED=true aún habilita la capa heredada de manifiesto/acciones en proceso en el transporte HTTP principal para compatibilidad local/de desarrollo. Esa capa usa autenticación de cadena de consulta MCP_AUTH_KEY y expone acciones más amplias, incluida la sobrescritura de páginas. No la use como la ruta recomendada para el conector ChatGPT alojado.

Estructura del Proyecto

El código base sigue una estructura modular dentro del directorio src/:

src/
├── index.ts           # Entry point: Initializes and starts the server
├── config/            # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/        # Core MCP server logic and capability registration
│   ├── server.ts      # Server setup, transport handling, tool/resource registration
│   ├── resources/     # MCP Resource implementations (currently none)
│   ├── tools/         # MCP Tool implementations (subdirs per tool)
│   └── transports/    # Stdio and HTTP transport logic, auth middleware
├── services/          # Abstractions for external APIs or internal caching
│   ├── obsidianRestAPI/ # Typed client for Obsidian Local REST API
│   └── vaultManager/    # Multi-vault configuration and service management
├── types-global/      # Shared TypeScript type definitions (errors, etc.)
└── utils/             # Common utility functions (logger, error handler, security, etc.)

Para un árbol de archivos detallado, ejecuta npm run tree o consulta docs/tree.md.

Servicio de Caché del Vault

Este servidor incluye una caché en memoria inteligente diseñada para mejorar el rendimiento y la resiliencia al interactuar con tu vault.

Propósito y Beneficios

Rendimiento: Al almacenar en caché el contenido y los metadatos de los archivos, el servidor puede realizar operaciones de búsqueda mucho más rápido, especialmente en vaults grandes. Esto reduce el número de solicitudes directas a la API REST Local de Obsidian, lo que resulta en una experiencia más ágil.
Resiliencia: La caché actúa como respaldo para la herramienta obsidian_global_search. Si la búsqueda en vivo de la API falla o expira, el servidor utiliza la caché sin problemas para proporcionar resultados, asegurando que la funcionalidad de búsqueda permanezca disponible incluso si la API de Obsidian no responde temporalmente.
Eficiencia: La caché está diseñada para ser eficiente. Realiza una construcción inicial al iniciar y luego se actualiza periódicamente en segundo plano comprobando las modificaciones de archivos, asegurando que se mantenga razonablemente actualizada sin un sondeo constante y pesado de la API.

Cómo Funciona

Inicialización: Cuando está habilitado, el VaultCacheService construye un mapa en memoria de todos los archivos .md en tu vault, almacenando su contenido y tiempos de modificación.
Actualización Periódica: La caché se actualiza automáticamente en un intervalo configurable (por defecto 10 minutos). Durante una actualización, solo obtiene contenido para archivos que son nuevos o que han sido modificados desde la última comprobación.
Actualizaciones Proactivas: Después de que un archivo se modifica mediante una herramienta como obsidian_update_file, el servicio actualiza proactivamente la caché para ese archivo específico, asegurando una consistencia inmediata.
Respaldo de Búsqueda: La herramienta obsidian_global_search primero intenta una búsqueda en vivo de la API. Si esto falla, automáticamente recurre a buscar en la caché en memoria.

Configuración

La caché está habilitada por defecto pero se puede configurar mediante variables de entorno:

OBSIDIAN_ENABLE_CACHE: Establécelo en true (por defecto) o false para habilitar o deshabilitar el servicio de caché.
OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN: Define el intervalo en minutos para la actualización periódica en segundo plano. Por defecto es 10.

Herramientas

El Obsidian MCP Server proporciona un conjunto de herramientas para interactuar con tus vault(s), invocables mediante el Model Context Protocol.

Soporte Multi-Vault

Todas las herramientas admiten un parámetro opcional vault para especificar sobre qué vault operar:

Comportamiento Predeterminado: Sin el parámetro vault, las herramientas usan el primer vault configurado
Vault Específico: Añade vault: "vault-id" para apuntar a un vault específico
Ejemplo: obsidian_read_file(filePath="note.md", vault="work")

Nombre de la Herramienta	Descripción	Argumentos Clave
`obsidian_read_file`	Recupera el contenido y los metadatos de un archivo.	`filePath`, `vault?`, `format?`, `includeStat?`
`obsidian_update_file`	Modifica un archivo añadiendo, anteponiendo o sobrescribiendo.	`targetType`, `content`, `vault?`, `targetIdentifier?`, `wholeFileMode`
`obsidian_search_replace`	Realiza operaciones de buscar y reemplazar en una nota.	`targetType`, `replacements`, `vault?`, `useRegex?`, `replaceAll?`
`obsidian_global_search`	Busca contenido en todo el vault.	`query`, `vault?`, `searchInPath?`, `useRegex?`, `page?`, `pageSize?`
`obsidian_list_files`	Lista archivos y subdirectorios en una carpeta.	`dirPath`, `vault?`, `fileExtensionFilter?`, `nameRegexFilter?`
`obsidian_manage_frontmatter`	Obtiene, establece o elimina claves en el frontmatter de una nota.	`filePath`, `operation`, `key`, `vault?`, `value?`
`obsidian_manage_tags`	Añade, elimina o lista etiquetas en una nota.	`filePath`, `operation`, `tags`, `vault?`
`obsidian_delete_file`	Elimina permanentemente un archivo del vault.	`filePath`, `vault?`
`obsidian_dataview_query`	Ejecuta consultas DQL de Dataview contra tu vault.	`query`, `vault?`, `format?`
`obsidian_task_query`	Busca y analiza tareas en todo tu vault.	`vault?`, `status?`, `dateRange?`, `folder?`, `priority?`, `format?`
`obsidian_periodic_notes`	Crea y gestiona notas diarias, semanales, mensuales y anuales.	`operation`, `periodType`, `vault?`, `date?`, `content?`, `append?`
`obsidian_block_reference`	Trabaja con referencias de bloques y operaciones de encabezados.	`operation`, `filePath`, `vault?`, `heading?`, `content?`, `blockId?`
`obsidian_graph_analysis`	Analiza conexiones de notas y relaciones del vault.	`operation`, `vault?`, `filePath?`, `minConnections?`, `maxDepth?`
`obsidian_template_system`	Crea archivos a partir de plantillas con sustitución de variables.	`operation`, `vault?`, `templatePath?`, `targetPath?`, `variables?`
`obsidian_smart_linking`	Obtén sugerencias y recomendaciones inteligentes de enlaces.	`operation`, `vault?`, `filePath?`, `content?`, `maxSuggestions?`

Nota: Todas las herramientas admiten un manejo integral de errores, enrutamiento multi-vault y devuelven respuestas JSON estructuradas.

Licencia

Este proyecto está licenciado bajo Apache License 2.0 - consulta el archivo LICENSE para más detalles.

Atribución

Esta versión mejorada se basa en el excelente trabajo de cyanheads en el proyecto original obsidian-mcp-server. Todo el crédito de la funcionalidad principal y la arquitectura corresponde al autor original.

Mejoras en este fork:

Soporte Multi-Vault: Acceso simultáneo a múltiples vaults de Obsidian con enrutamiento específico por vault
Integración MCP remota de Claude.ai y correcciones de compatibilidad
Integración de Tailscale Funnel para acceso remoto seguro
Capa de transporte HTTP mejorada con separación de autenticación (MCP_AUTH_KEY)
Consulta avanzada de tareas con integración del plugin Tasks
5 Nuevas Herramientas Avanzadas: Notas periódicas, referencias de bloques, análisis de grafos, sistema de plantillas y enlaces inteligentes
Configuración lista para producción para uso empresarial

Construido con el Model Context Protocol
Mejorado para Claude.ai Integración Remota