Obsidian via REST

Accede y gestiona tu bóveda de Obsidian a través de una API REST local.

Documentación

mcp-obsidian

Desplegado / Uso

Ask DeepWiki NPM Version GitHub Stars GitHub Forks NPM Downloads Docker Hub obsidian-mcp Docker Hub obsidian-vnc License: MIT

Estado de CI/CD

NPM (npmjs.org) NPM (GitHub)

Docker (GitHub) Docker (Docker Hub)

Screenshots Cleanup

mcp-obsidian
- Desplegado / Uso
- Estado de CI/CD
- Herramientas y Recursos MCP
  * Herramientas
  * Recursos
  * Prueba Rápida
- Configurar MCP
  * Configuración Multi-URL (Recomendada)
  * Configuración de Transporte HTTP
  * Configuración Desacoplada con Autenticación
  * Configuración de Transporte Stdio
  * Configuración Legada de URL Única
  * Endpoint de Salud
- Configuración de Herramientas CLI
  * CLI de Claude Code
  * CLI de Gemini
  * CLI de OpenCode
  * CLI de Kilo Code
  * CLI de Codex
  * CLI de GitHub Copilot
  * Referencia Rápida
- Configuración y Solución de Problemas
  * Configuración
  * Verificar que la API REST de Obsidian esté ejecutándose (Host Windows, MacOS, Linux)
  * WSL2, Docker alojado en Ubuntu
  * Verificar Firewall de Windows
  * Deshabilitar/Habilitar Firewall
  * Verificar Conectividad en Contenedor BusyBox
- Obsidian Dockerizado

Herramientas y Recursos MCP

Este servidor MCP expone las siguientes herramientas y recursos a los asistentes de IA:

Herramientas

Herramienta	Descripción	Parámetros
get_note_content	Recuperar contenido y metadatos de una nota de Obsidian	filePath (string) - Ruta a la nota
obsidian_search	Buscar notas usando una cadena de consulta	query (string) - Consulta de búsqueda
obsidian_semantic_search	Búsqueda semántica de notas	query (string) - Consulta de búsqueda

Recursos

Recurso	Patrón de URI	Descripción
Nota de Obsidian	obsidian://{path}	Acceder a notas vía URI (p. ej., obsidian://Daily/2025-01-16.md)

Prueba Rápida

1. Establece tu clave de API de Obsidian

export OBSIDIAN_API_KEY="tu-clave-de-api-rest-de-obsidian"

2. Agrega el servidor MCP y prueba (Claude Code)

claude mcp add obsidian -- bunx -y @oleksandrkucherenko/mcp-obsidian claude "Busca en mi bóveda de Obsidian herramientas de monitoreo, resume hallazgos"

2. Alternativa: CLI de Codex

codex mcp add obsidian --command "bunx -y @oleksandrkucherenko/mcp-obsidian" codex "Encuentra notas sobre frameworks de logging y crea una tabla comparativa"

Caso de uso de ejemplo: "Encuentra todas las herramientas en mi bóveda de Obsidian para rastrear logs y métricas, haz un informe resumido" — la IA busca en tu bóveda, encuentra notas sobre OpenTelemetry, Datadog, Prometheus, etc., y genera un resumen estructurado.

Para otras herramientas CLI (Gemini, OpenCode, Kilo Code, Copilot), consulta la Guía de Pruebas Manuales.

Gemini CLI Example

Configurar MCP

Configuración Multi-URL (Recomendada)

Usa API_URLS para conmutación por error automática y autocuración. El servidor prueba todas las URLs en paralelo, selecciona la más rápida y se reconecta automáticamente ante fallos.

{ "mcpServers": { "obsidian": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian", "--rm", "-i", // Mantener STDIN abierto para transporte stdio "-p", "3000:3000", "-e", "API_KEY", "-e", "API_URLS", "-e", "DEBUG", // para logs "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", // Arreglo JSON - prueba automáticamente y selecciona la URL más rápida "API_URLS": "["https://127.0.0.1:27124","https://172.26.32.1:27124","https://host.docker.internal:27124"]", "DEBUG": "mcp:*" } } } }

Características de Autocuración:

✅ Prueba de URLs en paralelo al inicio
✅ Selección automática de la URL más rápida
✅ Monitoreo de salud cada 30 segundos
✅ Conmutación por error automática ante pérdida de conexión
✅ Retroceso exponencial para evitar cambios constantes

Transportes disponibles:

stdio - Entrada/salida estándar (predeterminado, mejor para clientes MCP locales)
http - HTTP JSON-RPC con transmisión SSE (mejor para acceso remoto)

Ejemplo WSL2:

Determinar automáticamente la IP de puerta de enlace WSL

export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}')

Configurar con múltiples URLs de respaldo

API_URLS='["https://127.0.0.1:27124", "https://'$WSL_GATEWAY_IP':27124", "https://host.docker.internal:27124"]'

Configuración de Transporte HTTP

El servidor MCP admite transporte HTTP para acceso remoto con conmutación por error automática de URL:

{ "mcpServers": { "obsidian-http": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian-http", "--rm", "-p", "3000:3000", "-e", "API_KEY", "-e", "API_URLS", "-e", "MCP_HTTP_PATH", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", "API_URLS": "["https://127.0.0.1:27124","https://172.26.32.1:27124","https://host.docker.internal:27124"]", "MCP_HTTP_PATH": "/mcp" // ruta del endpoint (predeterminado: /mcp) } } } }

Configuración Desacoplada con Autenticación

ejecutar servidor MCP en docker por separado del IDE

docker run --name mcp-obsidian-http --rm
-p 3000:3000
-e API_KEY="<secret_key>"
-e API_URLS="${API_URLS}"
-e MCP_HTTP_TOKEN=
ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

{ "mcpServers": { "obsidian": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer " }
} } }

Los clientes deben incluir el encabezado Authorization:

Authorization: Bearer tu-token-secreto-aqui

Configuración de Transporte Stdio

Para desarrollo local con transporte stdio (predeterminado):

{ "mcpServers": { "obsidian": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian-windsurf", "--interactive", "--rm", "-e", "API_KEY", "-e", "API_URLS", "-e", "DEBUG", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", "API_URLS": "["https://127.0.0.1:27124","https://172.26.32.1:27124"]", "DEBUG": "mcp:*" // predeterminado: logs deshabilitados } } } }

--rm - Eliminar automáticamente el contenedor y sus volúmenes anónimos asociados al salir
-i, --interactive - Mantener STDIN abierto
-e, --env - Establecer variables de entorno
--name string - Asignar un nombre al contenedor
-p, --publish - Publicar el puerto del contenedor al host
Lanzamientos de Paquetes NPM
Lanzamientos de Imágenes Docker

Configuración Legada de URL Única

Para compatibilidad hacia atrás, aún puedes usar configuración de URL única con API_HOST y API_PORT:

{ "mcpServers": { "obsidian": { "command": "docker", "args": [ "run", "--name", "mcp-obsidian", "--rm", "-i", "-e", "API_KEY", "-e", "API_HOST", "-e", "API_PORT", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" ], "env": { "API_KEY": "<secret_key>", "API_HOST": "https://172.26.32.1", // URL única sin conmutación por error "API_PORT": "27124" } } } }

Nota: La configuración de URL única no proporciona conmutación por error automática ni monitoreo de salud. Usa API_URLS para despliegues de producción.

Endpoint de Salud

Cuando el transporte HTTP está habilitado, el servidor expone un endpoint de verificación de salud en /health:

curl http://localhost:3000/health

Respuesta:

{ "status": "healthy", "timestamp": "2025-01-12T12:00:00.000Z", "transport": "http", "authEnabled": false }

Para un estado de salud integral que incluya la conexión a la API de Obsidian y todos los transportes, puedes usar la función getHealthStatus() que devuelve:

{ "healthy": true, "obsidian": { "connected": true, "url": "https://obsidian:27124", "lastCheck": 1705065600000 }, "transports": { "stdio": { "running": true, "enabled": true }, "http": { "running": true, "enabled": true } }, "uptime": 3600, "timestamp": 1705065600000 }

Configuración de Herramientas CLI

Esta sección muestra cómo configurar herramientas CLI de IA populares para usar el servidor MCP de Obsidian.

MacOs o Linux

curl -fsSL https://bun.sh/install | bash

Windows

powershell -c "irm bun.sh/install.ps1 | iex"

CLI de Claude Code

Docker:

Crear configuración mcp.json

cat > mcp.json << 'EOF' { "mcpServers": { "obsidian": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "env": { "API_KEY": "", "API_URLS": "["https://host.docker.internal:27124"]" } } } } EOF

Ejecutar Claude con configuración MCP

claude --mcp-config ./mcp.json

NPX/Bunx:

cat > mcp.json << 'EOF' { "mcpServers": { "obsidian": { "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "API_KEY": "", "API_URLS": "["https://127.0.0.1:27124"]" } } } } EOF

claude --mcp-config ./mcp.json

CLI de Gemini

Docker:

gemini mcp add
-e API_KEY=
-e API_URLS='["https://host.docker.internal:27124"]'
obsidian
docker run --rm -i ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

NPX/Bunx:

gemini mcp add
-e API_KEY=
-e API_URLS='["https://127.0.0.1:27124"]'
obsidian
bunx -y @oleksandrkucherenko/mcp-obsidian

Transporte HTTP (servidor remoto):

gemini mcp add --transport http obsidian-http http://localhost:3000/mcp

Listar y gestionar servidores:

gemini mcp list gemini mcp remove obsidian

CLI de OpenCode

Crea opencode.json en la raíz de tu proyecto:

Docker:

{ "mcp": { "obsidian": { "type": "local", "command": ["docker", "run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "environment": { "API_KEY": "{env:API_KEY}", "API_URLS": "["https://host.docker.internal:27124"]" }, "enabled": true } } }

NPX/Bunx:

{ "mcp": { "obsidian": { "type": "local", "command": ["bunx", "-y", "@oleksandrkucherenko/mcp-obsidian"], "environment": { "API_KEY": "{env:API_KEY}", "API_URLS": "["https://127.0.0.1:27124"]" }, "enabled": true } } }

Transporte HTTP:

{ "mcp": { "obsidian-http": { "type": "remote", "url": "http://localhost:3000/mcp", "enabled": true } } }

CLI de Kilo Code

Crea .kilocode/mcp.json en tu proyecto o ~/.kilocode/cli/global/settings/mcp_settings.json globalmente:

Docker:

{ "mcpServers": { "obsidian": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "env": { "API_KEY": "", "API_URLS": "["https://host.docker.internal:27124"]" } } } }

NPX/Bunx:

{ "mcpServers": { "obsidian": { "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "API_KEY": "", "API_URLS": "["https://127.0.0.1:27124"]" } } } }

{ "mcpServers": { "obsidian-http": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer " } } } }

CLI de Codex

Docker:

Registrar servidor MCP

codex mcp add obsidian
--command "docker run --rm -i -e API_KEY -e API_URLS ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"
--env API_KEY=
--env 'API_URLS=["https://host.docker.internal:27124"]'

NPX/Bunx: codex mcp add obsidian
--command "bunx -y @oleksandrkucherenko/mcp-obsidian"
--env API_KEY=
--env 'API_URLS=["https://127.0.0.1:27124"]'

GitHub Copilot CLI

Crea ~/.copilot/mcp-config.json (o .copilot/mcp-config.json en la raíz del repositorio):

Docker:

{ "mcpServers": { "obsidian": { "type": "local", "command": "docker", "args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS", "ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"], "env": { "API_KEY": "${OBSIDIAN_API_KEY}", "API_URLS": "["https://host.docker.internal:27124"]" }, "tools": ["*"] } } }

NPX/Bunx:

{ "mcpServers": { "obsidian": { "type": "local", "command": "bunx", "args": ["-y", "@oleksandrkucherenko/mcp-obsidian"], "env": { "API_KEY": "${OBSIDIAN_API_KEY}", "API_URLS": "["https://127.0.0.1:27124"]" }, "tools": ["*"] } } }

Nota: Copilot CLI v0.0.340+ requiere la sintaxis ${VAR} para la expansión de variables de entorno. Establece OBSIDIAN_API_KEY en tu shell antes de ejecutar.

Referencia rápida

Herramienta CLI	Archivo de configuración	Soporte Docker	Transporte HTTP
Claude Code	mcp.json	✅	✅
Gemini	settings.json	✅	✅
OpenCode	opencode.json	✅	✅
Kilo Code	.kilocode/mcp.json	✅	✅
Codex	Comandos CLI	✅	✅
Copilot	~/.copilot/mcp-config.json	✅	✅

Para pruebas y verificación detalladas, consulta la Guía de Pruebas Manuales.

Configuración y Solución de Problemas

Configuración

Ejecuta la aplicación de escritorio de Obsidian y habilita Local REST API en Configuración.

Obsidian Local REST API Setup

Esta configuración te permitirá conectarte a la Local REST API desde cualquier interfaz de red (no solo localhost, lo cual es crítico para la configuración de WSL2).

Copia la API Key desde la Configuración de Obsidian; la necesitarás para la configuración del MCP.
Verifica que la Local REST API de Obsidian esté ejecutándose y sea accesible desde tu máquina.
El siguiente paso es siempre verificar la configuración de red en tu máquina (reglas de firewall, etc.).

Verificar que la API REST de Obsidian esté ejecutándose (Host Windows, MacOS, Linux)

Ejecuta en la terminal CMD de Windows:

windows CMD, verifica que el puerto esté escuchando (que la API REST esté ejecutándose)

netstat -an | findstr 27124

Salida esperada:

TCP 0.0.0.0:27124 0.0.0.0:0 LISTENING

Verifica que la Local REST API de Obsidian esté funcionando

curl --insecure https://localhost:27124 wget --no-check-certificate -S https://localhost:27124 http --verify=no https://localhost:27124

Respuesta esperada de la API REST:

{ "status": "OK", "manifest": { "id": "obsidian-local-rest-api", "name": "Local REST API", "version": "3.2.0", "minAppVersion": "0.12.0", "description": "Get, change or otherwise interact with your notes in Obsidian via a REST API.", "author": "Adam Coddington", "authorUrl": "https://coddingtonbear.net/", "isDesktopOnly": true, "dir": ".obsidian/plugins/obsidian-local-rest-api" }, "versions": { "obsidian": "1.8.10", "self": "3.2.0" }, "service": "Obsidian Local REST API", "authenticated": false }

WSL2, Docker alojado en Ubuntu

graph LR subgraph "Windows Machine" obs("Obsidian Application")

  subgraph "WSL2"
    subgraph "Ubuntu"
      subgraph "Docker"
        mcp("mcp-obsidian:latest")
      end
    end
  end

  firewall(["Windows Firewall"]) -->|27124| obs

  mcp -->|https://$WSL_GATEWAY_IP:27124| firewall

  IDE -.->|MCP Server Tools| mcp
end

Ejecuta dentro de la terminal de Ubuntu en WSL2:

export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}') echo $WSL_GATEWAY_IP # se espera algo como: 172.26.32.1

Verifica que la Local REST API de Obsidian esté funcionando

curl --insecure https://$WSL_GATEWAY_IP:27124 wget --no-check-certificate -S https://$WSL_GATEWAY_IP:27124 http --verify=no https://$WSL_GATEWAY_IP:27124

Verificar el Firewall de Windows

Ejecuta la GUI y configura manualmente las reglas:

Firewall de Windows Defender / Reglas de entrada. Presiona Win+R y escribe WF.msc o firewall.cpl

WF.msc firewall.cpl # y luego presiona 'Configuración avanzada'

O ejecuta en Windows PowerShell como Administrador:

Agrega una regla de firewall para permitir el puerto 27124 (Ejecutar en PowerShell como Administrador)

New-NetFirewallRule -DisplayName "WSL2 Obsidian REST API" -Direction Inbound -LocalPort 27123,27124 -Protocol TCP -Action Allow

O ejecuta en la terminal CMD de Windows:

verifica las reglas de firewall (CMD) que gestionan el puerto 27124

netsh advfirewall firewall show rule name=all | findstr /C:"Rule Name" /C:"LocalPort" /C:"RemotePort" | findstr /C:"27124"

muestra las reglas que tienen la palabra clave WSL2 en su nombre

netsh advfirewall firewall show rule name=all | grep -A 13 WSL2

muestra la definición de la regla por número de puerto (4 líneas después, 9 líneas antes)

netsh advfirewall firewall show rule name=all | grep -A 4 -B 9 27124

Deshabilitar/Habilitar Firewall

Ejecuta en Windows PowerShell como Administrador:

Apaga temporalmente el firewall (SOLO para pruebas, no recomendado para uso regular)

Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False

Restaura el estado del firewall

Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled True

Verificar la Conectividad en el Contenedor BusyBox

Estos pasos nos permiten confirmar que la configuración de red es correcta y que el contenedor puede conectarse a la Local REST API.

Ejecuta dentro de la terminal de Ubuntu en WSL2:

export WSL_GATEWAY_IP=$(ip route | grep default | awk '{print $3}') echo "IP del host Windows desde WSL2: $WSL_GATEWAY_IP"

Salida:

IP del host Windows desde WSL2: 172.26.32.1

ejecuta el contenedor docker para verificar la conectividad desde Docker dentro

docker run --rm -it --network=host busybox sh

dentro del contenedor ejecuta:

which wget

/bin/wget

export WINDOWS_HOST_IP="172.26.32.1" echo $WINDOWS_HOST_IP

172.26.32.1 intenta conectarte a la Local REST API

wget -qO- --no-check-certificate "https://$WINDOWS_HOST_IP:27124" wget -qO- --no-check-certificate https://172.26.32.1:27124

Obsidian en Docker

Obsidian Dockerizado