Obsidian Claude Code

Un plugin de Obsidian que integra Claude Code en tus bóvedas a través de un servidor MCP.

Documentación

Obsidian Claude Code

Un plugin de Obsidian que implementa un servidor MCP (Protocolo de Contexto de Modelo) para habilitar la integración de Claude Code con bóvedas de Obsidian.

Este plugin permite que Claude Code y otros clientes MCP (como Claude Desktop) interactúen con tu bóveda de Obsidian, proporcionando asistencia impulsada por IA con acceso directo a tus notas y archivos.

Características

Servidor MCP de Doble Transporte: Soporta tanto WebSocket (para Claude Code) como HTTP/SSE (para Claude Desktop)
Auto-Detección: Claude Code encuentra y se conecta automáticamente a tu bóveda
Operaciones de Archivos: Lee y escribe archivos de la bóveda a través del protocolo MCP
Contexto del Espacio de Trabajo: Proporciona el archivo activo actual y la estructura de la bóveda a Claude
Soporte para Múltiples Clientes: Conecta tanto Claude Code como Claude Desktop simultáneamente
Puertos Configurables: Evita conflictos al ejecutar múltiples bóvedas

Configuración del Cliente MCP

Este plugin actúa como un servidor MCP al que varios clientes de Claude pueden conectarse. Así es como configurar diferentes clientes:

Claude Desktop (a partir de 2025-06-09)

Claude Desktop requiere una configuración especial para conectarse al servidor MCP de Obsidian porque no soporta directamente transportes HTTP. Usaremos mcp-remote, una herramienta que crea un puente local stdio hacia el endpoint HTTP del servidor.

Pasos de Configuración:

Instala y habilita este plugin en Obsidian.
Asegúrate de tener Node.js instalado, ya que npx (que viene con Node.js) se usa para ejecutar la herramienta puente.
Localiza tu archivo de configuración de Claude Desktop:
- macOS: $HOME/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Agrega el servidor MCP de Obsidian a tu configuración usando el comando mcp-remote. npx lo descargará y ejecutará automáticamente por ti.
```
{
	"mcpServers": {
		"obsidian": {
			"command": "npx",
			"args": ["mcp-remote", "http://localhost:22360/sse"],
			"env": {}
		}
	}
}
```
Reinicia Claude Desktop después de realizar el cambio de configuración.
Prueba la conexión preguntándole a Claude sobre tu bóveda: "¿Qué archivos hay en mi bóveda de Obsidian?"

Otros Clientes MCP (con soporte HTTP directo)

Si estás usando un cliente MCP que soporta directamente el transporte heredado "HTTP con SSE", puedes usar una configuración más simple sin el puente mcp-remote.

Ejemplo de Configuración:

{
	"mcpServers": {
		"obsidian": {
			"url": "http://localhost:22360/sse",
			"env": {}
		}
	}
}

CLI de Claude Code

Claude Code descubre y se conecta automáticamente a las bóvedas de Obsidian a través de WebSocket.

Pasos de Uso:

Instala y habilita este plugin en Obsidian
Ejecuta Claude Code en tu terminal: claude
Selecciona tu bóveda usando el comando /ide
Elige "Obsidian" de la lista de IDE
Claude Code se conectará automáticamente vía WebSocket

Configuración de Puertos

Puerto Predeterminado: El plugin usa el puerto 22360 por defecto para evitar conflictos con servicios de desarrollo comunes.

Configuración de Puerto Personalizado:

Ve a Configuración de Obsidian → Plugins de Comunidad → Claude Code → Configuración
Cambia el "Puerto del Servidor HTTP" en la sección de Configuración del Servidor MCP

Actualiza tu configuración de Claude Desktop para usar el nuevo puerto:

{
	"mcpServers": {
		"obsidian": {
			"url": "http://localhost:22360/mcp",
			"env": {}
		}
	}
}

 NOTA: Puedes cambiar el puerto en la configuración.

Reinicia Claude Desktop para aplicar los cambios

Múltiples Bóvedas: Si ejecutas múltiples bóvedas de Obsidian con este plugin, cada bóveda necesita un puerto único. El plugin detectará automáticamente conflictos de puertos y te guiará para configurar puertos diferentes.

Una Nota sobre la Versión de la Especificación MCP

A partir de 2025-06-09

[!IMPORTANTE] Este plugin usa intencionalmente una especificación MCP más antigua para el transporte HTTP. El último "Protocolo HTTP Streamable" (2025-03-26) aún no es soportado por la mayoría de los clientes MCP, incluyendo Claude Code y Claude Desktop.

Para asegurar compatibilidad, usamos el protocolo heredado "HTTP con SSE" (2024-11-05). Adherirse a la especificación más nueva causará fallos de conexión con las herramientas actuales.

Solución de Problemas

Claude Desktop no se conecta:

Verifica la ruta del archivo de configuración y la sintaxis JSON
Asegúrate de que Obsidian esté ejecutándose con el plugin habilitado
Comprueba que el puerto (22360) no esté bloqueado por el firewall
Reinicia Claude Desktop después de los cambios de configuración

Claude Code no encuentra la bóveda:

Verifica que el plugin esté habilitado en Obsidian
Busca archivos .lock en el directorio de configuración de Claude:
- $CLAUDE_CONFIG_DIR/ide/ si la variable de entorno está configurada
- ~/.config/claude/ide/ (predeterminado desde Claude Code v1.0.30)
- ~/.claude/ide/ (ubicación heredada)
Reinicia Obsidian si la bóveda no aparece en la lista de /ide

Conflictos de puertos:

Configura un puerto diferente en la configuración del plugin
Actualiza las configuraciones del cliente para que coincidan con el nuevo puerto
Puertos alternativos comunes: 22361, 22362, 8080, 9090

Arquitectura de Herramientas

Este plugin implementa un sistema de herramientas flexible que permite exponer diferentes herramientas a diferentes clientes MCP:

Categorías de Herramientas

Herramientas Compartidas (disponibles tanto para clientes IDE como MCP):
- Operaciones de archivos: view, str_replace, create, insert
- Operaciones del espacio de trabajo: get_current_file, get_workspace_files
- Acceso a la API de Obsidian: obsidian_api
Herramientas Específicas del IDE (solo disponibles vía WebSocket de Claude Code):
- getDiagnostics - Diagnósticos del sistema y de la bóveda
- openDiff - Operaciones de vista de diferencias (stub para Obsidian)
- close_tab - Gestión de pestañas (stub para Obsidian)
- closeAllDiffTabs - Operaciones de pestañas en lote (stub para Obsidian)
Herramientas Solo MCP (solo disponibles vía HTTP/SSE):
- Actualmente ninguna, pero la arquitectura soporta agregarlas

Agregar Nuevas Herramientas

Para agregar una nueva herramienta al plugin:

Para Herramientas Compartidas (disponibles tanto para IDE como MCP):

Agrega la definición de la herramienta a src/tools/general-tools.ts en el array GENERAL_TOOL_DEFINITIONS
Agrega la implementación en el método createImplementations() de la clase GeneralTools
La herramienta estará automáticamente disponible tanto para clientes WebSocket como HTTP

Para Herramientas Específicas del IDE:

Agrega la definición de la herramienta a src/ide/ide-tools.ts en el array IDE_TOOL_DEFINITIONS
Agrega la implementación en el método createImplementations() de la clase IdeTools
La herramienta solo estará disponible para Claude Code vía WebSocket

Para Herramientas Solo MCP:

Agrega la definición de la herramienta a src/tools/mcp-only-tools.ts en el array MCP_ONLY_TOOL_DEFINITIONS
Crea una clase de implementación similar a GeneralTools o IdeTools
Actualiza src/mcp/dual-server.ts para registrar las herramientas solo en el registro HTTP

Flujo de Registro de Herramientas

El plugin usa un sistema de doble registro:

Registro WebSocket: Contiene herramientas compartidas + herramientas específicas del IDE
Registro HTTP: Contiene herramientas compartidas + herramientas solo MCP

Esta separación asegura que:

Claude Code obtenga acceso a funcionalidades específicas del IDE
Los clientes MCP estándar solo vean herramientas apropiadas
La funcionalidad compartida esté disponible para todos los clientes

Desarrollo

Este proyecto usa TypeScript para proporcionar verificación de tipos y documentación. El repositorio depende de la última API de plugins (obsidian.d.ts) en formato de Definición de TypeScript, que contiene comentarios TSDoc que describen lo que hace.

Publicación de Nuevas Versiones

Actualiza tu manifest.json con tu nuevo número de versión, como 1.0.1, y la versión mínima de Obsidian requerida para tu última versión.
Actualiza tu archivo versions.json con "new-plugin-version": "minimum-obsidian-version" para que versiones anteriores de Obsidian puedan descargar una versión anterior de tu plugin que sea compatible.
Crea una nueva versión de GitHub usando tu nuevo número de versión como "Tag version". Usa el número de versión exacto, no incluyas un prefijo v. Ver aquí un ejemplo: https://github.com/obsidianmd/obsidian-sample-plugin/releases
Sube los archivos manifest.json, main.js, styles.css como adjuntos binarios. Nota: El archivo manifest.json debe estar en dos lugares, primero en la ruta raíz de tu repositorio y también en la versión.
Publica la versión.