obsidian-mcp

Claude(및 모든 MCP 클라이언트)가 Obsidian 볼트에 실제 에이전트 수준으로 접근할 수 있도록 합니다. 그래프 탐색, Dataview 쿼리, 일일 노트 인식 등을 지원합니다.

설치 · 도구 · 추천 프롬프트 · 비교 · FAQ

대부분의 Obsidian MCP 서버는 read_file과 write_file만 제공하고 끝납니다. 이 서버는 여러분의 볼트를 지식 그래프로 취급합니다. LLM이 단 한 번의 호출로 백링크, 포워드 링크, Dataview 쿼리, 일일 노트, 다중 홉 그래프 탐색을 수행할 수 있습니다.

이유

Claude Desktop을 열고 노트 간의 연결을 찾으라고 요청했을 때, Claude가 노트 하나하나를 read_file로 읽어 나가는 것을 보셨을 겁니다. 하지만 Obsidian 사용자는 노트를 그런 식으로 생각하지 않습니다. 그래프 자체가 가치입니다. 백링크, 전이적 연결, 태그, Dataview 타입 메타데이터 등이 중요하죠. 이 서버는 이 모든 것을 일급 도구로 제공합니다.

설치

Obsidian에 Local REST API 플러그인이 필요합니다. 커뮤니티 플러그인에서 설치하고 활성화한 뒤, 설정에서 API 키를 복사하세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 다음을 추가하세요:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Claude Desktop을 재시작하세요. 완료되었습니다.

Claude Code

claude mcp add obsidian -e OBSIDIAN_API_KEY=paste-your-key-here -- npx -y obsidian-mcp

Cursor / Cline / Continue / Zed

MCP 호환 클라이언트라면 무엇이든 작동합니다. 환경 변수에 OBSIDIAN_API_KEY를 설정하고 npx -y obsidian-mcp를 가리키도록 하세요.

소스에서 설치

git clone https://github.com/yanxue06/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build
OBSIDIAN_API_KEY=... node dist/index.js

추천 프롬프트

서버가 연결된 Claude Desktop에 다음을 입력해 보세요:

분산 시스템에 대해 작성한 모든 내용을 바탕으로 콘텐츠 맵(MOC)을 만들어줘. "Distributed systems.md"에서 traverse_graph를 깊이 2로 사용하고, 이웃 노드들을 주제별로 그룹화한 뒤 MOCs/Distributed systems MOC.md에 MOC를 작성해줘.

#project 태그가 있고 status != "done"이며 마감일이 이번 주인 모든 노트를 찾아줘. query_dataview를 사용해.

오늘 일일 노트에 뭐가 있지? 어제 노트에서 후속 조치를 잊은 게 있을까?

Inbox/에 있는 고아 노트(orphan notes)를 모두 찾아줘. 각 노트의 내용과 기존 태그를 바탕으로 어디에 속해야 할지 제안해줘.

"Atomic notes.md"를 "Evergreen notes.md"로 이름을 바꾸려고 해. 이 노트를 링크하는 모든 노트를 찾아서 내가 업데이트해야 할 노트가 무엇인지 알려줘.

"Working memory.md"에서 2홉 떨어진 그래프를 탐색해서 주의력에 대한 내 생각의 중심이 되는 노트가 무엇인지 알려줘.

도구

총 15개의 도구가 있습니다. 차별화된 도구는 굵게 표시했습니다.

읽기

검색 및 그래프

쓰기

비교

설정

모든 설정은 환경 변수를 통해 이루어지며, MCP 클라이언트 설정에서 지정합니다.

작동 원리

┌──────────────┐     stdio (MCP)      ┌──────────────┐    HTTPS     ┌──────────────────┐
│ Claude / IDE │ ───────────────────► │ obsidian-mcp │ ───────────► │  Local REST API  │ ──► Vault
└──────────────┘                      └──────────────┘              │ (Obsidian plugin)│
                                                                    └──────────────────┘

obsidian-mcp는 Local REST API 플러그인 위에 구축된 얇은 레이어입니다. 이 플러그인은 Obsidian 내부에서 전체 볼트에 접근할 수 있는 HTTPS 서버를 실행합니다. 이 서버는 해당 인터페이스를 MCP 프로토콜에 맞게 조정하고, Obsidian의 REST API가 직접 제공하지 않는 그래프 인식 도구(백링크, 다중 홉 탐색, 고아 탐색 등)를 추가합니다.

모든 데이터는 로컬에 머뭅니다. MCP 클라이언트가 모델 제공자에게 보내는 요청 외에는 어떤 데이터도 기기를 떠나지 않으며, 이는 사용자가 제어할 수 있습니다.

FAQ

Obsidian 플러그인을 설치해야 하나요? 네, Local REST API 플러그인이 필요합니다. 외부에서 실행 중인 볼트와 통신할 수 있는 유일한 합리적인 방법입니다. 설치 후 obsidian-mcp 자체는 MCP 클라이언트에 의해 시작되는 별도의 Node 프로세스로 실행되므로, Obsidian에 추가 플러그인을 설치할 필요는 없습니다.

Obsidian이 닫혀 있어도 작동하나요? 아니요. Local REST API는 Obsidian 내부에서 실행되므로 앱이 열려 있어야 합니다.

여러 볼트를 지원하나요? 하나의 서버 인스턴스는 하나의 실행 중인 Obsidian 인스턴스를 가리킵니다. 볼트를 자주 전환한다면 여러 MCP 서버 항목(다른 이름 + 다른 포트)을 실행하세요.

왜 기본적으로 OBSIDIAN_VERIFY_TLS=false인 HTTPS를 사용하나요? 플러그인은 자체 서명 인증서를 제공합니다. 트래픽은 루프백(127.0.0.1) 내에서만 발생하므로, 검증은 실제 보안 이득 없이 번거로움만 더합니다. 인증서를 교체했다면 이 플래그를 설정하세요.

안전한가요? MCP 서버는 API 키가 허용하는 만큼의 접근 권한을 모델에 부여합니다. 모델이 삭제하려는 모든 것을 삭제할 수 있습니다. 파일 쓰기 권한이 있는 다른 에이전트와 마찬가지로 취급하고, 특히 대량 작업을 수행하기 전에 모델이 무엇을 하려는지 검토하세요.

로드맵

• [ ] 임베딩 기반 의미론적 검색 (현재는 플러그인을 통한 키워드 검색만 가능)

• [ ] 작업 공간 전환 / 다중 볼트 라우팅

• [ ] 읽기 전용 안전 모드 (쓰기 도구 등록 안 함)

• [ ] 리소스 구독 (노트 변경 시 업데이트 푸시)

• [ ] Smithery / mcp-get 레지스트리 제출

PR은 언제나 환영합니다. CONTRIBUTING.md를 참조하세요.

감사의 말

• @coddingtonbear의 Local REST API — 이 프로젝트의 기반입니다.

• Anthropic의 Model Context Protocol 팀.

라이선스

MIT — LICENSE를 참조하세요.