second-brain-mcp

모든 Obsidian 또는 일반 마크다운 볼트를 위한 읽기 전용 MCP 서버로, 검색 프로토콜을 말로 요청하는 대신 서버가 강제로 적용합니다.

마크다운 노트가 담긴 폴더를 지정하면 Claude Code, Claude Desktop, Cursor 등 모든 MCP 클라이언트가 네 가지 관리 도구를 통해 해당 지식 베이스를 질의할 수 있습니다. 서버는 구조적으로 쓸 수 없고, 볼트 디렉터리를 벗어날 수 없으며, 페이지 읽기 하드 예산에 도달하면 세션을 중단합니다.

왜 필요한가

개인 지식 베이스는 결국 하나의 도구에 종속되기 마련입니다. 노트는 Obsidian에 있고, 그 노트를 활용할 AI 어시스턴트는 다른 곳에 있으니 복사해서 붙여넣게 됩니다. 그리고 어시스턴트가 파일 접근 권한을 얻어도 "필요한 것만 읽어 주세요"라는 말은 규칙이 아니라 정중한 부탁일 뿐입니다.

이 서버는 두 문제를 모두 해결합니다:

• 하나의 커넥터로 모든 앱. MCP는 AI 도구의 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에 추가합니다(설정 → 개발자 → 구성 편집):

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

Cursor

~/.cursor/mcp.json에 같은 블록을 추가합니다(또는 Cursor 설정 → MCP → 새 서버 추가).

준비된 볼트가 없나요?

볼트 인자를 아예 생략하면 서버가 번들에 포함된 가상 데모 볼트("Alex Rivera")를 제공합니다. 30초 안에 시험해 보기에 유용합니다:

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

Obsidian 볼트 지정하기

볼트는 그냥 폴더입니다. Obsidian에서 "폴더를 볼트로 열기"라고 할 때 선택한 바로 그 폴더입니다. 그 폴더의 절대 경로를 인자로 전달하세요:

참고:

• 볼트 루트의 index.md 가 인덱스 우선 흐름(get_index)을 활성화합니다. 각 노트당 한 줄씩 기술된 카탈로그 페이지입니다. 이 파일이 없어도 모든 기능은 정상 작동합니다. 모델이 search_notes로 대체합니다.

• Obsidian 자체 구성(.obsidian/)과 기타 모든 점(dot) 폴더는 서버에 보이지 않습니다.

• 서버는 어떤 것도 수정하지 않으므로 실행 중에도 Obsidian을 열어 둘 수 있습니다.

사용법

연결되면 질문만 하면 됩니다. 일반적인 흐름은 다음과 같습니다(데모 볼트를 대상으로 한 실제 세션에서 가져옴):

"Alex Rivera는 무엇을 작업 중이고 Sam은 누구인가요?" → 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회) 이후 서버는 추가 읽기를 거부하고 모델에게 지금까지 읽은 내용을 바탕으로 종합하라고 안내합니다. 실패한 읽기는 예산을 소모하지 않습니다.

• 크기 상한. 노트는 50KB에서 잘리고, 검색 결과와 최근 목록도 상한이 적용됩니다.

• 점(dot) 폴더 건너뜀. .obsidian, .git 및 기타 점 폴더는 보이지 않습니다.

• 코드는 공개, 데이터는 비공개. 리포지토리에는 서버 코드와 가상의 데모 볼트만 포함됩니다. 실제 볼트는 런타임에 마운트한 폴더이며, 절대 사용자의 머신을 벗어나지 않습니다.

FAQ

내 데이터가 내 머신을 벗어나나요? 아니요. 서버는 MCP 클라이언트의 자식 프로세스로 로컬에서 실행되며 디스크에서 파일을 읽습니다. 네트워크 코드는 포함되어 있지 않습니다.

내 노트를 수정하거나 삭제할 수 있나요? 아니요. 쓰기 도구가 없습니다. 이는 설정이 아니라 코드 자체의 속성입니다.

모델이 예산을 소진하면 어떻게 되나요? 6번째 읽기는 모델에게 이미 읽은 페이지를 바탕으로 종합하라고 알리는 오류를 반환합니다. 새 대화에서는 새 예산이 부여됩니다.

데모 답변에 왜 "Alex Rivera"가 언급되나요? 번들로 제공되는 가상 데모 볼트를 사용 중이기 때문입니다. 첫 번째 인자로 자신의 볼트 경로를 전달하세요.

개발

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

스모크 테스트는 SDK 자체 클라이언트를 컴파일된 서버에 연결해 실제 프로토콜로 수행하며 목(mock)을 사용하지 않습니다. 네 가지 도구, 리소스, 프롬프트, 경로 이탈 거부, 그리고 읽기 예산이 N+1번째 읽기를 거부하는지 검증합니다. CI는 Linux와 Windows, Node 20 및 22에서 실행합니다.

이런 방식으로 만든 이유가 궁금하다면 docs/design-notes.md를 참조하세요. 전송 방식, MCP의 세 가지 기본 요소, 스키마를 프롬프트로 사용하는 방법, 샌드박스와 예산 결정에 대한 내용이 있습니다.

로드맵

• 인증을 포함한 원격 변형(스트리밍 가능한 HTTP)을 지원하여 호스팅 클라이언트에서도 볼트에 접근할 수 있게 하기

• 선택적 폴더별 범위 지정(wiki/만 제공하고 journal/ 숨기기)

기여

이슈와 PR을 환영합니다. 불변 조건을 지켜 주세요. 쓰기 도구 없음, 네트워크 호출 없음, 스모크 테스트가 약화되지 않고 계속 통과 상태를 유지해야 합니다.

라이선스

MIT · 변경 사항은 CHANGELOG.md를 참조하세요.