obsidian-mcp-server

Obsidian 자체 내부에서 Streamable HTTP 전송을 사용하여 MCP(Model Context Protocol) 서버를 실행하는 최소한의 Obsidian 플러그인입니다. list_notes, read_note, write_note, search_notes 네 가지 도구를 제공합니다.

전적으로 사용자 머신에서 실행됩니다(127.0.0.1에 바인딩) — 원격 클라이언트를 연결하지 않는 한 데이터가 PC를 떠나지 않습니다. 원격 클라이언트를 연결해서는 안 됩니다.

이 접근 방식의 이유

Obsidian 데스크톱 앱은 플러그인에서 Node 통합을 사용할 수 있는 Electron 앱이므로, 플러그인이 실제 http.Server를 열어 MCP와 직접 통신할 수 있습니다 — 외부 프로세스도, 계속 실행해야 하는 별도의 npx 서버도 필요 없습니다.

Related MCP server: obsidian-mcp

빌드 (Windows)

# 1. Put this folder inside your vault's plugin directory, e.g.:
#    <vault>\.obsidian\plugins\obsidian-mcp-server\

cd <vault>\.obsidian\plugins\obsidian-mcp-server
npm install
npm run build

이렇게 하면 manifest.json 옆에 main.js가 생성됩니다. 그런 다음 Obsidian에서: 설정 → 커뮤니티 플러그인 → "MCP Server"를 켭니다. MCP server listening on http://127.0.0.1:8123/mcp 알림이 표시되어야 합니다.

플러그인 설정을 열어 포트를 변경하거나 bearer 토큰을 설정할 수 있습니다.

Claude Desktop 연결

Claude Desktop의 로컬 mcpServers 구성은 raw URL이 아닌 stdio 명령을 기대하므로, mcp-remote로 HTTP 엔드포인트에 연결합니다(필요 시 npx로 설치되며 Node.js가 필요합니다):

%APPDATA%\Claude\claude_desktop_config.json 파일을 편집합니다:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8123/mcp"]
    }
  }
}

플러그인 설정에서 bearer 토큰을 설정한 경우 이를 헤더로 전달하세요:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://127.0.0.1:8123/mcp",
        "--header", "Authorization:Bearer YOUR_TOKEN"
      ]
    }
  }
}

트레이 아이콘에서 Claude Desktop을 종료한 후 다시 엽니다. 그러면 네 가지 Obsidian 도구를 표시하는 도구 아이콘이 나타날 것입니다.

디버깅

• MCP Inspector를 사용하여 Claude Desktop 없이 서버를 직접 테스트하세요: npx @modelcontextprotocol/inspector를 실행하고 http://127.0.0.1:8123/mcp에 연결합니다.

• Obsidian의 개발자 콘솔(Ctrl+Shift+I)에서 요청 오류를 포함한 플러그인의 console.error 출력을 확인할 수 있습니다.

확장

main.ts의 buildMcpServer()에서 도구를 더 추가하세요 — 예를 들어 frontmatter/태그 쿼리를 위해 app.metadataCache를 감싸거나, "현재 열려 있는 노트"를 확인하기 위해 app.workspace를 감싸면 됩니다. 각 도구는 그저 이름, zod 입력 스키마, { content: [...] }를 반환하는 비동기 핸들러일 뿐입니다.

참고 사항 / 주의사항

• 매니페스트의 isDesktopOnly: true — Obsidian 모바일에는 원시 http 모듈이 없으므로 로드되지 않습니다.

• 여기서 사용하는 무상태(stateless) 전송 모드(요청마다 새로운 StreamableHTTPServerTransport)는 가장 간단한 옵션이며 단일 로컬 클라이언트에 적합합니다. 제대로 된 세션 연속성을 갖춘 여러 동시 클라이언트가 필요하다면 Mcp-Session-Id 키 기반 전송 맵을 추가하면 됩니다 — MCP TypeScript SDK의 "with session management" 예제를 참조하세요.

• bearer 토큰은 실제 인증이 아닌 기본적인 공유 비밀 키 검사입니다. 서버가 127.0.0.1에만 바인딩되므로 주요 위협 모델은 "사용자 머신의 다른 로컬 프로세스"이며, 토큰은 바로 이를 해결합니다.