Obsidian Local REST API

Interactúa con tu bóveda local de Obsidian usando una API REST.

Documentación

Servidor MCP de Obsidian Local REST API

Un servidor MCP (Model Context Protocol) nativo para IA que proporciona herramientas inteligentes y orientadas a tareas para interactuar con bóvedas de Obsidian a través de una API REST local.

🧠 Filosofía de Diseño Nativo para IA

Este servidor MCP ha sido rediseñado siguiendo principios nativos para IA en lugar de un simple mapeo de API a herramientas. En lugar de exponer operaciones CRUD de bajo nivel, proporciona herramientas de alto nivel orientadas a tareas que los LLMs pueden razonar de manera más efectiva.

Antes vs Después: La Transformación

Enfoque Antiguo (Basado en CRUD)	Enfoque Nuevo (Nativo para IA)	Por Qué es Mejor
`list_files` (devuelve todo)	`list_directory(path, limit, offset)`	Previene el desbordamiento de contexto con paginación
`create_file` + `update_file`	`write_file(path, content, mode)`	Una sola herramienta maneja crear/actualizar/añadir
`create_note` + `update_note`	`create_or_update_note(path, content, frontmatter)`	Upsert inteligente elimina la complejidad de decisión
`search_notes(query)`	`search_vault(query, scope, path_filter)`	Búsqueda precisa y limitable con filtrado avanzado
(sin equivalente)	`get_daily_note(date)`	Abstracción de alto nivel para flujos de trabajo comunes
(sin equivalente)	`get_recent_notes(limit)`	Acceso a archivos recientes orientado a tareas
(sin equivalente)	`find_related_notes(path, on)`	Descubrimiento de relaciones conceptuales

🛠 Herramientas Disponibles

Operaciones de Directorio y Archivos

`list_directory`

Propósito: Listar contenidos de directorio con paginación para prevenir el desbordamiento de contexto

{
  "path": "Projects/",
  "recursive": false,
  "limit": 20,
  "offset": 0
}

Beneficio para IA: El LLM puede explorar la estructura de la bóveda incrementalmente sin abrumar el contexto

`read_file`

Propósito: Leer el contenido de cualquier archivo en la bóveda

{"path": "notes/meeting-notes.md"}

`write_file`

Propósito: Escribir archivos con múltiples modos - reemplaza las operaciones separadas de crear/actualizar

{
  "path": "notes/summary.md",
  "content": "# Meeting Summary\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

Beneficio para IA: Una sola herramienta maneja todos los escenarios de escritura, elimina la ambigüedad

`delete_item`

Propósito: Eliminar cualquier archivo o directorio

{"path": "old-notes/"}

Operaciones de Notas Nativas para IA

`create_or_update_note`

Propósito: Upsert inteligente - crea si falta, actualiza si existe

{
  "path": "daily/2024-12-26",
  "content": "## Tasks\n- Review AI-native MCP design",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

Beneficio para IA: Elimina el árbol de decisión "¿existe esta nota?"

`get_daily_note`

Propósito: Recuperación inteligente de notas diarias con patrones de nombres comunes

{"date": "today"}  // or "yesterday", "2024-12-26"

Beneficio para IA: Abstrae los detalles del sistema de archivos y las convenciones de nombres

`get_recent_notes`

Propósito: Obtener notas modificadas recientemente

{"limit": 5}

Beneficio para IA: Coincide con consultas naturales como "¿en qué trabajé recientemente?"

Búsqueda Avanzada y Descubrimiento

`search_vault`

Propósito: Búsqueda multi-ámbito con filtrado avanzado

{
  "query": "machine learning",
  "scope": ["content", "filename", "tags"],
  "path_filter": "research/"
}

Beneficio para IA: Búsqueda precisa y dirigida reduce el ruido

`find_related_notes`

Propósito: Descubrir relaciones conceptuales entre notas

{
  "path": "ai-research.md",
  "on": ["tags", "links"]
}

Beneficio para IA: Habilita flujos de trabajo basados en relaciones y descubrimiento fortuito

Herramientas Heredadas (Compatibilidad Hacia Atrás)

El servidor mantiene compatibilidad hacia atrás con herramientas existentes como get_note, list_notes, get_metadata_keys, etc.

Requisitos Previos

Node.js 18+ o runtime de Bun
Obsidian Local REST API ejecutándose localmente (predeterminado: http://obsidian-local-rest-api.test)

Instalación

Usando npx (Recomendado)

npx obsidian-local-rest-api-mcp

Desde el Código Fuente

# Clone the repository
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# Install dependencies with bun
bun install

# Build the project
bun run build

Configuración

Establezca variables de entorno para la conexión API:

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # Default URL (or http://localhost:8000 for non-Valet setups)
export OBSIDIAN_API_KEY="your-api-key"          # Optional bearer token

Uso

Ejecutando el Servidor

# Development mode with auto-reload
bun run dev

# Production mode
bun run start

# Or run directly
node build/index.js

Configuración del Cliente MCP

Claude Desktop

Añada a su claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["obsidian-local-rest-api-mcp"],
      "env": {
        "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
        "OBSIDIAN_API_KEY": "your-api-key-if-needed"
      }
    }
  }
}

VS Code con Extensión MCP

Use el archivo de configuración .vscode/mcp.json incluido.

Desarrollo

# Watch mode for development
bun run dev

# Build TypeScript
bun run build

# Type checking
bun run tsc --noEmit

Arquitectura

ObsidianApiClient - Envoltorio de cliente HTTP para endpoints de API REST
ObsidianMcpServer - Implementación del servidor MCP con manejadores de herramientas
Configuración - Configuración basada en entorno con validación

Manejo de Errores

El servidor incluye manejo integral de errores:

Fallos de conexión API
Parámetros de herramienta inválidos
Tiempos de espera de red
Errores de autenticación

Los errores se devuelven como respuestas de llamadas a herramientas MCP con mensajes descriptivos.

Depuración

Habilite el registro de depuración estableciendo variables de entorno:

export DEBUG=1
export NODE_ENV=development

Los registros del servidor se escriben en stderr para evitar interferir con la comunicación del protocolo MCP en stdout.

Solución de Problemas

El Servidor MCP No Se Inicia

Si su cliente MCP muestra "Start Failed" o errores similares:

Pruebe el servidor directamente:
```
npx obsidian-local-rest-api-mcp --version
```
Debería mostrar el número de versión.

Pruebe el protocolo MCP:

# Run our test script
node -e "
const { spawn } = require('child_process');
const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
child.stdout.on('data', d => console.log('OUT:', d.toString()));
child.stderr.on('data', d => console.log('ERR:', d.toString()));
setTimeout(() => {
  child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
  setTimeout(() => child.kill(), 2000);
}, 500);
"

Debería mostrar la respuesta de inicialización.

Verifique las Variables de Entorno:
- Asegúrese de que OBSIDIAN_API_URL apunte a una instancia de Obsidian Local REST API en ejecución
- Pruebe la API directamente: curl http://obsidian-local-rest-api.test/api/files (o su URL de API configurada)
Verifique Obsidian Local REST API:
- Instale y ejecute Obsidian Local REST API
- Confirme que sea accesible en el puerto configurado
- Verifique si se requiere autenticación

Problemas Comunes

"Command not found": Asegúrese de que Node.js/npm esté instalado y npx esté disponible

"Connection refused": Obsidian Local REST API no está ejecutándose o la URL es incorrecta

Dominios .test de Laravel Valet: Si usa Laravel Valet, asegúrese de que el nombre de su directorio de proyecto coincida con el dominio .test (por ejemplo, obsidian-local-rest-api.test para un proyecto en /obsidian-local-rest-api/)

"Unauthorized": Verifique si se requiere una clave API y si está configurada correctamente

"Timeout": Aumente el tiempo de espera en la configuración del cliente o verifique la conectividad de red

Configuración de Cherry Studio

Para Cherry Studio, use estos ajustes exactos:

Nombre: obsidian-vault (o cualquier nombre que prefiera)
Tipo: Standard Input/Output (stdio)
Comando: npx
Argumentos: obsidian-local-rest-api-mcp
Variables de Entorno:
- OBSIDIAN_API_URL: Su URL de API (por ejemplo, http://obsidian-local-rest-api.test para Laravel Valet)
- OBSIDIAN_API_KEY: Clave API opcional si se requiere autenticación
Variables de Entorno:
- OBSIDIAN_API_URL: http://obsidian-local-rest-api.test (o su URL de API)
- OBSIDIAN_API_KEY: your-api-key (si es necesario)

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Realice cambios con tipos TypeScript adecuados
Pruebe con su bóveda de Obsidian
Envíe una solicitud de extracción

Licencia

MIT