second-brain-mcp

Сервер MCP только для чтения для любого хранилища Obsidian или обычного markdown, в котором протокол поиска обеспечивается сервером, а не запрашивается в текстовой форме.

Укажите папку с markdown-заметками, и любой MCP-клиент — Claude Code, Claude Desktop, Cursor и любой другой — сможет запрашивать эту базу знаний через четыре управляемых инструмента. Сервер физически не может записывать, не может выйти за пределы каталога хранилища и завершает сеанс после жёсткого лимита прочитанных страниц.

Зачем

Личные базы знаний в итоге оказываются привязаны к одному инструменту. Заметки живут в Obsidian, а ИИ-ассистент, который мог бы их использовать, живёт где-то ещё, поэтому приходится копировать и вставлять. А когда ассистент действительно получает доступ к файлам, «пожалуйста, читай только то, что нужно» — это вежливая просьба, а не правило.

Этот сервер решает обе проблемы:

• Один коннектор — любое приложение. MCP — это USB-C для ИИ-инструментов: напишите коннектор к хранилищу один раз, и любой MCP-клиент сможет им пользоваться.

• Протокол — закон, а не рекомендация. Поиск через индекс, жёсткий лимит чтения страниц, доступ только для чтения и песочница путей реализованы в коде. Существуют только управляемые операции.

Related MCP server: obsidian_mcp

Установка

Требуется Node.js 18 или новее.

Вариант A — из npm

claude mcp add second-brain -- npx -y @nanthansr/second-brain-mcp /abs/path/to/your/vault

Эта единственная команда регистрирует сервер в Claude Code; npx автоматически загружает и запускает пакет. Для других клиентов см. блоки конфигурации ниже.

Вариант B — из исходников

git clone https://github.com/nanthansr/second-brain-mcp
cd second-brain-mcp
npm install && npm run build
npm test   # 15-check integration suite - should end with SMOKE PASS
claude mcp add second-brain -- node /abs/path/to/second-brain-mcp/dist/index.js /abs/path/to/your/vault

Claude Desktop

Добавьте в claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "second-brain": {
      "command": "npx",
      "args": ["-y", "@nanthansr/second-brain-mcp", "/abs/path/to/your/vault"]
    }
  }
}

Cursor

Добавьте тот же блок в ~/.cursor/mcp.json (или Cursor Settings → MCP → Add new server).

Нет под рукой хранилища?

Полностью опустите аргумент хранилища, и сервер предложит встроенное вымышленное демонстрационное хранилище («Alex Rivera») — удобно, чтобы попробовать за 30 секунд:

claude mcp add second-brain-demo -- npx -y @nanthansr/second-brain-mcp

Подключение к вашему хранилищу Obsidian

Ваше хранилище — это просто папка, которую вы выбрали, когда Obsidian спросил «Open folder as vault». Передайте абсолютный путь к этой папке в качестве аргумента:

Примечания:

• index.md в корне хранилища открывает сценарий «сначала индекс» (get_index): страница-каталог с одной строкой на заметку. Если у вас его нет, всё по-прежнему работает — модель переключается на search_notes.

• Собственная конфигурация Obsidian (.obsidian/) и любые другие скрытые папки невидимы для сервера.

• Сервер никогда ничего не изменяет — Obsidian может оставаться открытым во время его работы.

Использование

После подключения просто задавайте вопросы. Типичные сценарии (из реального сеанса с демонстрационным хранилищем):

«Над чем работает Алекс Ривера и кто такой Сэм?» → get_index → read_note ×3 (каждый вызов с пометкой read 1/5, read 2/5, read 3/5) → ответ с цитатами.

«Что изменилось в моём хранилище за эту неделю?» → list_recent(days: 7) → список с датами, сначала новые.

«Где у меня заметки про ценообразование?» → search_notes(query: "pricing") → подходящие страницы с фрагментами и номерами строк, без расхода лимита.

Клиенты, поддерживающие MCP-промпты, также получают vault-retrieval — шаблон слеш-команды, который закрепляет за моделью протокол «сначала индекс» для заданного вопроса.

Что получает клиент

Предполагаемый поток повторяет то, как аккуратный человек работает с вики: прочитать каталог, открыть одну-две нужные страницы, ответить с цитатами. Поиск дёшев; чтение ограничено.

Конфигурация

Модель безопасности

• Только чтение по построению. В кодовой базе не существует инструментов записи, редактирования или удаления.

• Песочница путей. Каждый путь сначала нормализуется через path.resolve, затем проверяется относительно корня хранилища — попытки выхода за пределы (../…) отклоняются. Читать можно только файлы .md.

• Жёсткий лимит страниц. После N вызовов read_note (по умолчанию 5) сервер отказывает в дальнейшем чтении и предлагает модели синтезировать ответ на основе уже прочитанного. Неудачные чтения не расходуют лимит.

• Ограничения размера. Заметки обрезаются на 50 КБ; результаты поиска и списки недавних ограничены по размеру.

• Скрытые папки пропускаются. .obsidian, .git и другие скрытые папки невидимы.

• Код публичен, данные — нет. В репозитории только код сервера и вымышленное демонстрационное хранилище. Ваше настоящее хранилище — это любая папка, которую вы подключаете во время запуска; оно никогда не покидает ваш компьютер.

Частые вопросы

Покидают ли мои данные мой компьютер? Нет. Сервер запускается локально как дочерний процесс вашего MCP-клиента и читает файлы с диска. В нём нет сетевого кода.

Может ли он изменять или удалять мои заметки? Нет. Инструментов записи не существует. Это свойство кода, а не настройка.

Что происходит, когда модель исчерпывает лимит? Шестое чтение возвращает ошибку с предложением модели синтезировать ответ из уже прочитанных страниц. Новый разговор получает новый лимит.

Почему демонстрационный ответ говорил об «Алексе Ривере»? Вы работаете со встроенным вымышленным демонстрационным хранилищем. Передайте путь к своему хранилищу первым аргументом.

Разработка

npm run build   # tsc -> dist/
npm test        # build + 15-check smoke test (spawns the real server over stdio)

Смоук-тест использует собственный клиент SDK против скомпилированного сервера — реальный протокол, без моков. Он проверяет все четыре инструмента, ресурс, промпт, отклонение выхода за пределы пути и то, что лимит чтения отказывает в чтении N+1-й страницы. CI запускает его на Linux и Windows, Node 20 и 22.

Любопытно, почему всё устроено именно так? См. docs/design-notes.md — транспорты, три примитива MCP, схемы как промпты, а также решения о песочнице и лимите.

Дорожная карта

• Удалённый вариант (streamable HTTP), чтобы хранилище было доступно из хостинг-клиентов, с аутентификацией

• Опциональное ограничение по папкам (обслуживать только wiki/, скрывать journal/)

Участие

Приветствуются issue и pull request. Соблюдайте инварианты: никаких инструментов записи, никаких сетевых вызовов, смоук-тест остаётся зелёным и не ослабленным.

Лицензия

MIT · Изменения в CHANGELOG.md