obsidian-mcp

공식 Obsidian CLI를 래핑하는 MCP 서버로, LLM 에이전트가 실행 중인 Obsidian 인스턴스를 제어할 수 있게 합니다. 노트 읽기/쓰기, 검색, 프런트매터 관리, 링크 탐색, 플러그인 실행 등을 수행할 수 있습니다.

이 서버는 가볍고 포괄적인 래퍼입니다. 모든 도구는 obsidian CLI 명령과 1:1로 매핑됩니다.

사전 요구 사항

1. Obsidian이 실행 중이어야 합니다. CLI는 IPC를 통해 실행 중인 앱과 통신하며, 디스크의 볼트를 직접 읽지 않습니다.

2. CLI 바이너리 등록. Obsidian에서: 설정 → 일반 → 명령줄 인터페이스 → CLI 등록. Obsidian이 PATH에 obsidian을 추가합니다.

3. 확인: obsidian version 명령으로 CLI 버전을 출력합니다.

설치

직접 빌드할지, npm에서 미리 게시된 버전을 가져올지에 따라 두 가지 경로가 있습니다.

옵션 A — 복제 및 빌드 (현재 사용 가능)

저장소를 복제하고 로컬에서 빌드한 다음, Claude Code가 빌드된 파일을 가리키도록 합니다:

git clone https://github.com/yuchichang/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build

Claude Code에 등록합니다 (명령어 하나로):

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user는 전체 사용자 계정에 등록합니다. 대신 저장소의 .mcp.json에 커밋하려면 -s project를 사용하거나, 현재 프로젝트에만 적용하려면 -s local (기본값)을 사용하세요.

또는 .mcp.json에 수동으로 작성하세요:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"]
    }
  }
}

옵션 B — npm에서 설치 (빌드 불필요)

사전 요구 사항: 패키지가 이미 npm에 게시되어 있어야 합니다. 관리자가 npm publish를 통해 한 번 게시하면, 이후 모든 사용자는 npx를 통해 자동으로 가져올 수 있습니다. 이 저장소를 포크하고 자신의 스코프에서 이 흐름을 사용하려면 package.json의 name을 @<your-npm-username>/obsidian-mcp로 변경한 후 npm publish를 수행하세요.

게시된 후에는 복제나 빌드가 필요 없습니다:

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

또는 .mcp.json / Claude Desktop의 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

CLI 경로 재정의

obsidian이 PATH에 없는 경우 OBSIDIAN_CLI 환경 변수를 설정하세요. 두 설치 경로 모두에서 작동합니다:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

도구

볼트 및 파일

프런트매터 속성

검색

태그 및 링크

데일리 노트

플러그인

개발자 / 고급

메타

규칙

• 노트 대상 지정 — 파일 대상 도구는 다음 중 하나를 허용합니다:

  • file — 위키링크 스타일의 노트 이름 (예: "My Note"), 또는

  • path — 볼트 상대 파일 경로 (예: "Folder/My Note.md").

• 다중 볼트 설정 — 모든 도구는 선택적 vault 매개변수를 허용합니다. 생략하면 가장 최근에 포커스된 볼트가 사용됩니다.

• 출력 형식 — 목록/검색/메타데이터 도구는 기계 파싱이 쉽도록 기본적으로 JSON을 사용합니다.

민감한 작업 및 사용자 확인

다음 도구는 사용자 확인 단계를 거쳐야 합니다:

확인 절차 작동 방식:

1. MCP 유도 (권장). 연결된 클라이언트가 elicitation 기능을 지원하는 경우(Claude Code 지원), 서버는 elicitation/create 요청을 보내고 클라이언트는 사용자에게 작업과 대상이 명시된 진행하시겠습니까? 프롬프트를 표시합니다. accept + confirm: true인 경우에만 진행됩니다.

2. 명시적 confirm: true 매개변수. 모든 민감한 도구의 입력 스키마에는 선택적 confirm: boolean이 포함되어 있습니다. confirm: true를 전달하면 유도 프롬프트를 건너뜁니다. 호출자가 이미 사용자 승인을 받은 경우에만 사용하세요.

3. 거부 폴백. 클라이언트가 유도를 지원하지 않고 confirm: true가 제공되지 않은 경우, 도구는 작업을 명시하고 confirm: true와 함께 재시도하도록 지시하는 isError 결과를 반환합니다.

배치 / 자동화를 위한 우회

OBSIDIAN_MCP_AUTO_CONFIRM=1

모든 확인 프롬프트를 건너뛰려면 이 환경 변수를 (MCP 클라이언트의 env 블록에) 설정하세요. 완전히 신뢰할 수 있는 자동화 컨텍스트에서만 사용하세요.

긴 콘텐츠 및 argv 제한

Obsidian CLI는 아직 stdin이나 파일에서 매개변수 값을 읽는 것을 지원하지 않습니다. 모든 값은 명령줄을 통해 전달됩니다. 이는 플랫폼 제한과 충돌합니다:

안전을 위해 서버는 긴 쓰기 작업을 자동으로 청크(chunk) 처리합니다:

가능한 경우 줄 경계에서 분할이 발생하며, 너무 긴 단일 줄은 UTF-8 안전 문자 경계로 폴백됩니다. 재조립된 콘텐츠는 원본과 바이트 단위로 동일합니다.

호출당 바이트 임계값을 구성하세요 (기본값: Windows 6,000, 기타 100,000):

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

다중 청크 쓰기 중간에 청크가 실패하면, 서버는 어떤 청크가 디스크에 기록되었는지 명확한 메시지와 함께 isError를 반환하여 호출자가 복구할 수 있도록 합니다.

개발

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

작동 원리

runObsidian() (src/exec.ts)은 인수를 셸 인용하고, child_process.exec를 통해 obsidian 바이너리를 호출하며, stdout을 파싱합니다. 대부분의 읽기 도구는 format=json을 요청하며, 결과는 구조화된 도구 출력을 소비하는 클라이언트를 위해 structuredContent로 파싱되지만, content에는 여전히 텍스트 표현이 반환됩니다.

도구 레지스트리는 src/tools.ts에 있으며, 새로운 래핑 명령을 추가하는 것은 해당 파일에 항목을 하나 추가하는 것만큼 간단합니다.

참조

• Obsidian CLI: https://obsidian.md/help/cli

• MCP 사양: https://modelcontextprotocol.io