Obsidian Knowledge MCP

Импортер из Obsidian в PostgreSQL и MCP-сервер, работающие в режиме только для чтения. Хранилище является источником истины: импорт читает Markdown-файлы и никогда не редактирует и не удаляет их.

Architecture

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

Документы сохраняют свои относительные пути и исходный текст Markdown. Каждая заметка становится узлом document; [[links]] становятся направленными рёбрами related_to и document_links. Теги, псевдонимы, заголовки и нераспознанный frontmatter сохраняются в JSONB. Отсутствующие цели ссылок заносятся в журнал и пропускаются. Повторный запуск импорта обновляет записи по пути к файлу и предотвращает появление дубликатов рёбер/тегов.

Related MCP server: Semantic Notes Vault MCP

Настройка

Требования: Python 3.11+, Docker Desktop и клиент PostgreSQL — только если вы хотите вручную просматривать SQL.

1. Скопируйте .env.example в .env, задайте POSTGRES_PASSWORD и укажите в OBSIDIAN_VAULT_PATH существующее хранилище. Не помещайте хранилище внутрь этого проекта, если вы этого не хотите.

2. Создайте окружение и установите зависимости:

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

3. Запустите PostgreSQL. Порт привязан только к localhost:

   docker compose up -d postgres

4. Импортируйте хранилище:

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

5. Проверьте его:

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

Схема монтируется как сценарий инициализации. Для существующего тома применяйте изменения явно с помощью psql -f database/schema.sql.

Развёртывание на Render

Этот репозиторий включает render.yaml для бесплатного веб-сервиса Render. В Render создайте новый Blueprint из этого репозитория и разверните его. Render сгенерирует MCP_AUTH_TOKEN и будет использовать свой PORT. Поскольку Render требует платёжную информацию для своего управляемого сервиса PostgreSQL, укажите DATABASE_URL от бесплатного внешнего провайдера PostgreSQL, например Neon или Supabase. Примените database/schema.sql к этой базе данных перед выполнением запросов. Публичная конечная точка по умолчанию:

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

Если вы измените имя сервиса, обновите MCP_PUBLIC_URL в окружении Render, указав итоговый URL https://<service-name>.onrender.com. Не добавляйте /mcp к MCP_PUBLIC_URL; /mcp должен быть только в URL коннектора Claude.

Сервис Render не может читать хранилище Windows или OneDrive. Импортируйте хранилище во внешнюю базу данных PostgreSQL с машины, у которой есть доступ и к хранилищу, и к базе данных, либо добавьте отдельное задание хранения/импорта, доступное из Render, перед выполнением запросов.

MCP-сервер

Запустите локально с помощью:

python -m mcp_server.server

Конечная точка по умолчанию — http://127.0.0.1:8000/mcp с использованием Streamable HTTP. Для локальных клиентов установите MCP_TRANSPORT=stdio и используйте obsidian-mcp в качестве команды. Сервер предоставляет search_knowledge, get_node, get_document, get_related_nodes, find_path, list_nodes и search_documents, а также ресурсы knowledge://node/{node_name}. Лимиты ограничены 100, а SQL-запросы параметризованы.

Коннектор Claude

Коннекторам Claude нужна удалённо доступная MCP-конечная точка, а не конечная точка PostgreSQL. В Claude Settings -> Connectors добавьте URL Render, оканчивающийся на /mcp, например https://obsidian-knowledge-mcp.onrender.com/mcp. Когда появится запрос, используйте сгенерированный MCP_AUTH_TOKEN в качестве bearer-токена, пройдите процедуру аутентификации, требуемую вашим рабочим пространством Claude, а затем проверьте работу с помощью запроса What do I have in my knowledge base about Python?.

Для продакшена используйте прокси, учитывающий идентичность (OAuth/OIDC), или mTLS вместо статического токена. Не открывайте порт 5432. Если Claude сообщает об ошибке подключения, проверьте docker compose ps, docker compose logs postgres, журналы процесса MCP, сертификат HTTPS/DNS, проброс /mcp через прокси и доступность конечной точки из внешней сети. Держите аутентифицированную проверку работоспособности отдельно от ошибок базы данных и не раскрывайте трассировки стека.

Примеры запросов

• Какие концепции связаны с машинным обучением?

• Найдите путь связей между Python и искусственным интеллектом.

• Какие концепции находятся в пределах двух переходов от RAG?

• Какие документы упоминают и Python, и машинное обучение?

Допущения и точки расширения

В этом рабочем пространстве не было хранилища для осмотра, поэтому парсинг следует стандартным соглашениям Obsidian и покрыт фикстурами в tests/test_parser.py. Синтаксис, специфичный для Dataview, сохраняется как содержимое. Репозиторный слой изолирует SQL от MCP, что делает возможной будущую двунаправленную синхронизацию без изменения контракта MCP. MCP_AUTH_TOKEN проверяется сервером Streamable HTTP; используйте прокси, учитывающий идентичность (OAuth/OIDC), для более строгого контроля доступа в продакшене.