Obsidian

Interactúa con tu bóveda de Obsidian desde tu IDE o Claude Desktop.

Documentación

Servidor MCP de Obsidian

Un servidor MCP (Model Context Protocol) que permite a los agentes de IA trabajar dentro de una bóveda de Obsidian: leer notas, buscar contexto, inspeccionar enlaces, seguir reglas específicas de la bóveda y, opcionalmente, crear o editar notas de forma segura.

Está diseñado para clientes y entornos como Codex, Claude Code, Hermes y Claude Desktop. El núcleo sigue siendo reutilizable; cada bóveda puede añadir sus propios perfiles, reglas, habilidades y conjuntos de herramientas opcionales.

Las herramientas son genéricas. El comportamiento proviene de la bóveda.

Example Obsidian vault graph generated through the MCP server

flowchart LR
    Clients["Codex, Claude Code, Hermes, Claude Desktop"] --> MCP["Obsidian MCP Server"]
    MCP --> Core["Core tools: read, search, inspect, route"]
    MCP --> Optional["Optional tool sets: write, graph, canvas, ObsidianRAG"]
    Core --> Vault["Obsidian vault"]
    Optional --> Vault
    Vault --> Profile[".agents/vault.yaml, rules, skills, standards"]
    Profile --> MCP

Características

Núcleo público

El conjunto de herramientas principal está siempre disponible y permanece independiente de la bóveda:

Diagnóstico de la bóveda, enrutamiento de tareas e inspección de la raíz del cliente MCP.
Listado de notas, lectura, inspección de metadatos y búsqueda.
Recursos de contexto de la bóveda para perfiles, habilidades, estándares y documentación local.
Prompts principales para notas estructuradas, uso de plantillas y exploración de contexto.

Conjuntos de herramientas opcionales

Los paquetes opcionales se habilitan explícitamente desde .agents/vault.yaml o OBSIDIAN_MCP_TOOL_SETS:

notes_write: Crear, modificar, mover y eliminar notas.
vault_analysis: Estadísticas de la bóveda, etiquetas, enlaces, backlinks y herramientas de grafo.
agents_admin: Creación de habilidades, validación y gestión de caché.
youtube: Extracción de transcripciones.
obsidianrag: Búsqueda semántica a través del servicio externo ObsidianRAG.
canvas / kanvas: Asistentes de canvas y flujos de trabajo.
Paquetes de perfil: Flujos de trabajo personales solo cuando un perfil de la bóveda los activa.

Principios de diseño

Núcleo público, perfiles personales: El repositorio sigue siendo reutilizable; los flujos de trabajo locales viven en la configuración y los recursos de la bóveda.
Superficie técnica en inglés: Los nombres de herramientas, nombres de prompts, documentación e identificadores de código están en inglés.
Seguro por defecto: Las herramientas de escritura son opcionales, las rutas protegidas están bloqueadas y las lecturas grandes están limitadas.
RAG externo por integración: La búsqueda semántica avanzada delega en ObsidianRAG en lugar de duplicar una pila RAG dentro del servidor MCP.

Inicio rápido

Requisitos previos

uv
Una ruta de bóveda de Obsidian que te sientas cómodo exponiendo a un cliente MCP

Instalación beta desde Git

Hasta que el paquete se publique en PyPI, instala directamente desde GitHub con uvx:

uvx --from git+https://github.com/Vasallo94/obsidian-mcp-server.git obsidian-mcp-server

Para Codex, añade esto a ~/.codex/config.toml:

[mcp_servers.obsidian]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/Vasallo94/obsidian-mcp-server.git",
  "obsidian-mcp-server",
]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.obsidian.env]
OBSIDIAN_VAULT_PATH = "/absolute/path/to/your/vault"

Para la configuración de Claude Code, Hermes, Claude Desktop y MCPB, consulta Instalación.

Desarrollo local

git clone https://github.com/Vasallo94/obsidian-mcp-server.git
cd obsidian-mcp-server
make install
cp .env.example .env
# Set OBSIDIAN_VAULT_PATH to the absolute path to your Obsidian vault
uv run obsidian-mcp-server

Una vez que el paquete se publique en PyPI, las configuraciones de cliente pueden usar:

uvx obsidian-mcp-server

Uso

Conjuntos de herramientas opcionales

Habilita las herramientas opcionales desde el entorno del cliente:

{
  "env": {
    "OBSIDIAN_VAULT_PATH": "/Absolute/Path/To/Your/Vault",
    "OBSIDIAN_MCP_TOOL_SETS": "notes_write,vault_analysis,obsidianrag"
  }
}

O decláralas en tu perfil de bóveda:

profile:
  name: "my_profile"
  prompt_sets:
    - "mermaid"
  tool_sets:
    - "notes_write"
    - "vault_analysis"
  standards:
    media: "Standards/Media.md"
  local_docs:
    index: "README.md"

Integración con ObsidianRAG

Para la búsqueda semántica en la bóveda, habilita el conjunto de herramientas obsidianrag y declara la integración:

profile:
  tool_sets:
    - "obsidianrag"
  integrations:
    obsidianrag:
      project_path: "/path/to/ObsidianRAG"
      api_url: "http://127.0.0.1:8000"
      env:
        OBSIDIANRAG_LLM_MODEL: "gemma3"
        OBSIDIANRAG_OLLAMA_EMBEDDING_MODEL: "embeddinggemma"

Luego lee obsidian://integrations/obsidianrag/setup o llama a rag.setup_status. Los agentes deben mostrar los comandos de configuración antes de instalar dependencias, iniciar servicios, descargar modelos o reconstruir el índice.

Documentación técnica

Para profundizar en cómo funciona el servidor y cómo personalizarlo, consulta nuestras guías detalladas en la carpeta docs/:

Inicio de documentación: Mapa estilo wiki de la documentación del proyecto.
Instalación: Configuración para Codex, Claude Code, Hermes, Claude Desktop y MCPB.
Arquitectura: Arquitectura en tiempo de ejecución, conjuntos de herramientas, recursos, prompts y modelo de seguridad.
Referencia de herramientas: Lista completa de herramientas MCP públicas.
Configuración del servidor: Variables de entorno, perfiles de bóveda, conjuntos de herramientas e integraciones.
Configuración del agente: Cómo organizar tu bóveda (.agents/) con habilidades y reglas contextuales.
Búsqueda semántica: Integración con ObsidianRAG y notas de migración del RAG heredado.
Comentarios del agente: Cómo los agentes pueden informar fricciones con MCP mediante AFP fuera de banda.
Hoja de ruta futura: Mejoras planificadas y próximos pasos para el servidor.

Para el proceso de contribución, publicación y seguridad, consulta CONTRIBUTING.md, SECURITY.md y Lista de verificación de publicación.

Desarrollo y calidad

Comando	Descripción
`make test`	Ejecutar la suite de pruebas (pytest)
`make lint`	Ejecutar comprobaciones estáticas (Ruff + Pyright)
`make format`	Formatear código automáticamente
`make dev`	Ejecutar el servidor MCP localmente

Licencia

Este proyecto está licenciado bajo la Licencia MIT.