Servidor MCP de Obsidian

Un servidor de Protocolo de Contexto de Modelo diseñado para que los LLM interactúen con las bóvedas de Obsidian. Desarrollado con TypeScript y con comunicación API segura, operaciones de archivos eficientes y funciones de búsqueda completas, permite a los asistentes de IA gestionar bases de conocimiento de forma fluida mediante una interfaz de herramientas clara y flexible.

El Protocolo de Contexto de Modelo (MCP) permite que los modelos de IA interactúen con herramientas y recursos externos a través de una interfaz estandarizada.

Requiere el complemento API REST local en Obsidian.

Características

Operaciones con archivos

Operaciones atómicas de archivos y directorios con validación
Monitoreo y limpieza de recursos
Manejo de errores y fallos elegantes

Sistema de búsqueda

Búsqueda de texto completo con contexto configurable
Consultas JsonLogic avanzadas para archivos, etiquetas y metadatos
Soporte para patrones glob y campos frontmatter

Administración de propiedades

Análisis de frontmatter de YAML y fusión inteligente
Marcas de tiempo automáticas (creadas por Obsidian, modificadas por el servidor)
Soporte de campos personalizados

Seguridad y rendimiento

Autenticación de clave API con limitación de velocidad y opciones SSL
Monitoreo de recursos y controles de salud
Manejo elegante del apagado

Instalación

Nota: Requiere Node.js

Habilitar el complemento API REST local en Obsidian
Clonar y construir:

git clone git@github.com:cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build

O instalar desde npm:

npm install obsidian-mcp-server

Configuración

Agregue a la configuración de su cliente MCP (por ejemplo, claude_desktop_config.json o cline_mcp_settings.json ):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/build/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here",
        "VERIFY_SSL": "false",
        "OBSIDIAN_PROTOCOL": "https",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "REQUEST_TIMEOUT": "5000",
        "MAX_CONTENT_LENGTH": "52428800",
        "MAX_BODY_LENGTH": "52428800",
        "RATE_LIMIT_WINDOW_MS": "900000",
        "RATE_LIMIT_MAX_REQUESTS": "200",
        "TOOL_TIMEOUT_MS": "60000"
      }
    }
  }
}

Variables de entorno:

Requerido:

OBSIDIAN_API_KEY : Su clave API de la configuración del complemento API REST local de Obsidian

Configuración de conexión:

VERIFY_SSL : Habilitar la verificación de certificados SSL (predeterminado: falso). # Debe configurarse como falso para certificados autofirmados. Si se ejecuta localmente o no comprende su significado, debe configurarse como falso.
OBSIDIAN_PROTOCOL : Protocolo a utilizar (predeterminado: "https")
OBSIDIAN_HOST : Dirección del host (predeterminada: "127.0.0.1")
OBSIDIAN_PORT : Número de puerto (predeterminado: 27124)

Límites de solicitud:

REQUEST_TIMEOUT : Tiempo de espera de la solicitud en milisegundos (valor predeterminado: 5000)
MAX_CONTENT_LENGTH : Longitud máxima del contenido de la respuesta en bytes (valor predeterminado: 52428800 [50 MB])
MAX_BODY_LENGTH : Longitud máxima del cuerpo de la solicitud en bytes (valor predeterminado: 52428800 [50 MB])

Limitación de velocidad:

RATE_LIMIT_WINDOW_MS : Ventana de límite de velocidad en milisegundos (valor predeterminado: 900000 [15 minutos])
RATE_LIMIT_MAX_REQUESTS : Máximo de solicitudes por ventana (predeterminado: 200)

Ejecución de la herramienta:

TOOL_TIMEOUT_MS : Tiempo de espera de ejecución de la herramienta en milisegundos (valor predeterminado: 60000 [1 minuto])

Estructura del proyecto

El proyecto sigue una arquitectura modular con una clara separación de preocupaciones:

src/
  ├── index.ts          # Main entry point
  ├── mcp/              # MCP server implementation
  ├── obsidian/         # Obsidian API client and types
  ├── resources/        # MCP resource implementations
  ├── tools/            # MCP tool implementations
  │   ├── files/        # File operations tools
  │   ├── search/       # Search tools
  │   └── properties/   # Property management tools
  └── utils/            # Shared utilities

Herramientas

Gestión de archivos

// List vault contents
obsidian_list_files_in_vault: {
}

// List directory contents
obsidian_list_files_in_dir: {
  dirpath: string; // Path relative to vault root
}

// Get file contents
obsidian_get_file_contents: {
  filepath: string; // Path relative to vault root
}

Operaciones de búsqueda

// Text search with context
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // Default: 10
}

// Advanced search with JsonLogic
obsidian_complex_search: {
  query: JsonLogicQuery
  // Examples:
  // Find by tag:
  // {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  //
  // Find markdown files in a directory:
  // {"glob": ["docs/*.md", {"var": "path"}]}
  //
  // Combine conditions:
  // {"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}
}

// Get all tags in vault or directory
obsidian_get_tags: {
  path?: string  // Optional: limit to specific directory
}

Modificación de contenido

// Append to file
obsidian_append_content: {
  filepath: string,  // Path relative to vault root
  content: string    // Content to append
}

// Update file content
obsidian_patch_content: {
  filepath: string,  // Path relative to vault root
  content: string    // New content (replaces existing)
}

Administración de propiedades

// Get note properties
obsidian_get_properties: {
  filepath: string  // Path relative to vault root
}

// Update note properties
obsidian_update_properties: {
  filepath: string,  // Path relative to vault root
  properties: {
    title?: string,
    author?: string,
    // Note: created/modified timestamps are managed automatically
    type?: Array<"concept" | "architecture" | "specification" |
      "protocol" | "api" | "research" | "implementation" |
      "guide" | "reference">,
    tags?: string[],  // Must start with #
    status?: Array<"draft" | "in-progress" | "review" | "complete">,
    version?: string,
    platform?: string,
    repository?: string,  // URL
    dependencies?: string[],
    sources?: string[],
    urls?: string[],      // URLs
    papers?: string[],
    custom?: Record<string, unknown>
  }
}

Mejores prácticas

Operaciones con archivos

Utilice operaciones atómicas con validación
Manejar errores y monitorear el rendimiento

Implementación de búsqueda

Utilice la herramienta de búsqueda adecuada para la tarea:
- obsidian_find_in_file para búsqueda de texto
- obsidian_complex_search para filtrado de metadatos/etiquetas
Mantenga el tamaño del contexto razonable (predeterminado: 10 caracteres)

Administración de propiedades

Utilice tipos apropiados y valide las actualizaciones
Manejar matrices y campos personalizados correctamente
Nunca establezca marcas de tiempo (administradas automáticamente)

Prevención de errores

Validar las entradas y manejar los errores con elegancia
Monitorear patrones y respetar límites de velocidad

Recursos

El servidor MCP expone los siguientes recursos:

obsidian://tags  # List of all tags used across the vault

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Enviar una solicitud de extracción

Para errores y características, cree un problema en https://github.com/cyanheads/obsidian-mcp-server/issues .

Publicación

El paquete se publica automáticamente en npm cuando se envían las etiquetas de versión:

# Update version in package.json
npm version patch  # or minor, or major
git push --follow-tags

Esto activará la acción de GitHub para crear y publicar el paquete.

Licencia

Licencia Apache 2.0

Obsidian MCP Server

Integrations

Servidor MCP de Obsidian

Características

Operaciones con archivos

Sistema de búsqueda

Administración de propiedades

Seguridad y rendimiento

Instalación

Configuración

Estructura del proyecto

Herramientas

Gestión de archivos

Operaciones de búsqueda

Modificación de contenido

Administración de propiedades

Mejores prácticas

Operaciones con archivos

Implementación de búsqueda

Administración de propiedades

Prevención de errores

Recursos

Contribuyendo

Publicación

Licencia

Tools

Related Resources

Appeared in Searches