Obsidian Knowledge MCP

Un importador de solo lectura de Obsidian a PostgreSQL y servidor MCP. La bóveda es la fuente de verdad: la ingesta lee los archivos Markdown y nunca los edita ni los elimina.

Arquitectura

Obsidian vault -> Python parser/upsert importer -> PostgreSQL -> FastMCP tools/resources -> Claude Connector

Los documentos conservan sus rutas relativas y el cuerpo original en Markdown. Cada nota se convierte en un nodo document; los [[links]] se convierten en aristas dirigidas related_to y en document_links. Las etiquetas, los alias, los encabezados y el frontmatter no reconocido se conservan en JSONB. Los destinos de enlace que faltan se registran y se omiten. Volver a ejecutar la ingesta actualiza los registros por ruta de archivo y evita aristas/etiquetas duplicadas.

Related MCP server: Semantic Notes Vault MCP

Configuración

Requisitos: Python 3.11+, Docker Desktop y un cliente de PostgreSQL solo si quieres inspeccionar el SQL manualmente.

1. Copia .env.example a .env, define POSTGRES_PASSWORD y configura OBSIDIAN_VAULT_PATH con la ruta de la bóveda existente. No pongas la bóveda dentro de este proyecto a menos que quieras tenerla ahí.

2. Crea el entorno e instala las dependencias:

   py -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -e ".[test]"

3. Inicia PostgreSQL. El puerto está enlazado solo a localhost:

   docker compose up -d postgres

4. Importa la bóveda:

   python -m ingestion.importer
   # or: obsidian-ingest "C:\path\to\vault"

5. Verifícalo:

   docker compose exec postgres psql -U knowledge_app -d knowledge -c "select count(*) from documents; select count(*) from edges;"
   pytest

El esquema se monta como script de inicialización. Para un volumen existente, aplica los cambios explícitamente con psql -f database/schema.sql.

Despliegue en Render

Este repositorio incluye render.yaml para un Web Service gratuito de Render. En Render, crea un nuevo Blueprint desde este repositorio y despliégalo. Render generará MCP_AUTH_TOKEN y usará su PORT. Como Render requiere información de pago para su servicio de PostgreSQL gestionado, proporciona DATABASE_URL de un proveedor externo gratuito de PostgreSQL, como Neon o Supabase. Aplica database/schema.sql a esa base de datos antes de consultarla. El endpoint público por defecto es:

https://obsidian-knowledge-mcp.onrender.com/mcp

Si cambias el nombre del servicio, actualiza MCP_PUBLIC_URL en el entorno de Render con la URL resultante https://<service-name>.onrender.com. No añadas /mcp a MCP_PUBLIC_URL; /mcp solo corresponde a la URL del conector de Claude.

El servicio de Render no puede leer una bóveda de Windows ni de OneDrive. Importa la bóveda a la base de datos PostgreSQL externa desde una máquina que pueda acceder tanto a la bóveda como a la base de datos, o añade una tarea de almacenamiento/importación independiente accesible desde Render antes de consultarla.

Servidor MCP

Ejecútalo localmente con:

python -m mcp_server.server

El endpoint por defecto es http://127.0.0.1:8000/mcp mediante Streamable HTTP. Para clientes locales, define MCP_TRANSPORT=stdio y usa obsidian-mcp como comando. El servidor expone search_knowledge, get_node, get_document, get_related_nodes, find_path, list_nodes y search_documents, además de los recursos knowledge://node/{node_name}. Los límites están fijados en 100 y el SQL está parametrizado.

Conector de Claude

Los conectores de Claude necesitan un endpoint MCP accesible de forma remota, no un endpoint de PostgreSQL. En Claude Settings -> Connectors, añade la URL de Render que termine en /mcp, por ejemplo https://obsidian-knowledge-mcp.onrender.com/mcp. Cuando se te solicite, usa el MCP_AUTH_TOKEN generado como token de portador, completa el flujo de autenticación requerido por tu espacio de trabajo de Claude y prueba con What do I have in my knowledge base about Python?.

Para producción, usa un proxy consciente de identidad (OAuth/OIDC) o mTLS en lugar de un token estático. No expongas el puerto 5432. Si Claude informa de un error de conexión, comprueba docker compose ps, docker compose logs postgres, los registros del proceso MCP, el certificado HTTPS/DNS, el reenvío del proxy de /mcp y si el endpoint es accesible desde fuera de tu red. Mantén una comprobación de estado autenticada separada de los errores de base de datos y no expongas trazas de pila.

Consultas de ejemplo

• ¿Qué conceptos están conectados con Machine Learning?

• Encuentra la ruta de relación entre Python e Inteligencia Artificial.

• ¿Qué conceptos están a dos saltos de RAG?

• ¿Qué documentos mencionan tanto Python como Machine Learning?

Supuestos y puntos de extensión

No había ninguna bóveda disponible en este espacio de trabajo para inspeccionarla, por lo que el parseo sigue las convenciones estándar de Obsidian y está cubierto por los fixtures de tests/test_parser.py. La sintaxis específica de Dataview se conserva como contenido. La capa de repositorio aísla el SQL del MCP, lo que hace posible una futura sincronización bidireccional sin cambiar el contrato MCP. MCP_AUTH_TOKEN se aplica mediante el servidor Streamable HTTP; usa un proxy consciente de identidad (OAuth/OIDC) para un control de acceso de producción más sólido.