obsidian-cli-mcp

실행 중인 Obsidian 보관소를 공식 Obsidian CLI(Obsidian 1.12+)를 통해 완전히 제어할 수 있게 해주는 MCP 서버로, 정확성이 허용되는 경우 빠른 직접 파일 시스템 읽기를 제공합니다.

things-for-mac-mcp의 동반 프로젝트입니다.

무엇이 다른가요?

대부분의 Obsidian MCP 서버는 커뮤니티 REST 플러그인과 통신하거나 보관소 폴더를 직접 읽습니다. 전자는 플러그인을 설치하고 신뢰해야 합니다. 후자는 파일을 이동하거나 이름을 바꾸는 순간 위키링크를 조용히 깨뜨리는데, 그 이유는 Obsidian만이 해당 파일을 가리키는 모든 링크, 별칭, 임베드를 알고 있기 때문입니다.

이 서버는 각 작업을 기능별로 라우팅합니다:

아키텍처는 자매 프로젝트와 정확히 동일합니다:

분할의 규칙: 대량 읽기는 처리량이 필요하므로 파일 시스템으로 가고, 이동, 이름 변경, 삭제 또는 링크 해결이나 앱 상태에 의존하는 모든 것은 CLI를 통해 처리됩니다. 왜냐하면 Obsidian의 지식이 필요하기 때문입니다. 파일 시스템 어댑터는 구조적으로 보관소를 변경할 수 없으며, 쓰기 함수를 전혀 내보내지 않습니다.

요구 사항

• Obsidian 1.12 이상이 설치된 macOS, Windows 또는 Linux 데스크톱

• Obsidian CLI 활성화: Obsidian, 설정, 일반, 명령줄 인터페이스

• Obsidian이 실행 중이어야 합니다. CLI는 앱의 클라이언트이지 독립 실행형 바이너리가 아닙니다. 데스크톱 전용이며, 모바일은 지원되지 않습니다.

• Node.js 18 이상

설치

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

MCP 클라이언트에 연결

Claude (Desktop / Code)

claude_desktop_config.json에 추가 (Claude Desktop) 또는 claude mcp add 실행 (Claude Code):

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

node의 절대 경로를 사용하세요. 단순한 단어가 아닙니다. GUI로 실행된 앱은 셸의 PATH를 상속하지 않으므로 "command": "node"는 많은 클라이언트에서 조용히 실패합니다. which node로 경로를 찾으세요.

둘 이상의 보관소가 있는 경우 OBSIDIAN_VAULT를 설정하세요. 그렇지 않으면 CLI는 마지막으로 포커스된 보관소를 대상으로 하는데, 이는 자동화된 쓰기에 매우 좋지 않은 속성입니다. 단일 보관소의 경우 서버가 시작 시 자동으로 고정합니다.

구성

보호 장치

세 가지 티어, 바이너리가 생성되기 전에 적용됨:

• 티어 1, 무료: 읽기, 검색, 추가 쓰기 (create_note, append_note, append_daily, set_property, update_task, capture).

• 티어 2, confirm: true 필요: delete_note, move_note, rename_note, remove_property, run_obsidian_command, 그리고 패스스루를 통해: history:restore, publish:*, plugin:enable/disable/reload, theme:*, snippet:*, sync, sync:restore, reload, template:insert, workspace:save/delete. overwrite 또는 permanent 플래그가 있는 모든 호출도 티어 2로 상향됩니다.

• 티어 3, OBSIDIAN_MCP_ALLOW_DANGEROUS=1로 서버가 실행되지 않으면 차단됨: eval, restart, plugin:install, plugin:uninstall, plugins:restrict, devtools, dev:cdp, dev:debug, dev:mobile, 그리고 permanent: true가 있는 delete_note.

이것들이 무엇인지에 대한 솔직한 설명. 티어 2는 우발적인 호출에 대한 속도 제한일 뿐, 보안이 아닙니다: 호출 모델이 스스로 confirm: true를 설정할 수 있습니다. 티어 3은 실제 경계입니다. 서버 환경을 구성하는 사람만이 잠금을 해제할 수 있기 때문입니다. 소중한 보관소를 가리키는 자율 에이전트를 사용하는 경우, OBSIDIAN_MCP_READONLY=1로 실행하세요. 이는 디스패치 전에 티어에 관계없이 모든 변경 명령을 거부합니다.

링크 안전 이동 및 이름 변경

이 프로젝트에서 가장 중요한 규칙: 파일은 파일 시스템을 통해 이동, 이름 변경, 삭제되지 않습니다. Obsidian은 작업을 수행할 때 보관소의 모든 위키링크를 업데이트합니다. 단순한 mv는 그렇지 않습니다.

이전, 세 개의 노트에서 연결된 Projects/Roadmap.md:

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

move_note 후 to: "Archive/2026 Roadmap.md" 사용:

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

세 개의 링크 모두 업데이트되었습니다. 헤딩 앵커와 별칭을 포함하여, Obsidian이 이동을 수행했기 때문입니다. 파일 시스템 이동은 세 개의 끊어진 링크와 오류 없음을 남겼을 것입니다.

왜 하이브리드인가? 성능 근거

모든 CLI 호출은 실행 중인 Obsidian 앱을 통한 한 번의 전체 IPC 왕복입니다. 정확하지만 느립니다: obsidian read로 2,000개의 노트를 읽는 것은 2,000번의 왕복, 수 분의 실제 시간이 걸립니다. 디스크에서 읽는 것은 한 번의 디렉터리 탐색이며, 모든 SSD에서 1초 미만입니다.

따라서 대량 읽기(검색, 목록, 태그 및 속성 스캔, 내보내기, 요약)는 파일 시스템을 사용하고, CLI는 Obsidian만이 답할 수 있는 것(링크, 별칭, Bases, 템플릿, 앱 상태)과 모든 쓰기를 위해 예약됩니다. 자신의 보관소에서 비교하려면 search_notes와 패스스루 obsidian_cli를 ["search", "query=..."]로 시간을 측정하세요.

문제 해결

"Obsidian이 실행 중이 아닙니다." 가장 흔한 실패. CLI는 앱이 열려 있고 완전히 로드되어 있어야 합니다. Obsidian을 시작하고 다시 시도하세요.

"Obsidian CLI 바이너리를 찾을 수 없습니다." Obsidian의 설정, 일반, 명령줄 인터페이스에서 CLI를 활성화하거나 OBSIDIAN_BIN을 바이너리로 지정하세요.

첫 번째 명령에서 타임아웃. 차가운 Obsidian 시작은 기본 20초를 초과할 수 있습니다. OBSIDIAN_MCP_TIMEOUT을 높이세요.

노트가 누락된 것으로 읽히거나 서버가 자주 CLI로 대체됨. 보관소가 iCloud에 있고 'Mac 저장 공간 최적화'가 켜져 있으면, 제거된 파일은 .name.icloud 스텁으로만 존재합니다. 서버는 이를 감지하고 Obsidian을 통해 읽어서 다시 다운로드하며, 빈 노트로 보고하지 않습니다. 대량 스캔은 제거된 파일을 건너뛰고 출력에 그 사실을 명시합니다.

쓰기가 잘못된 보관소에 기록됨. 여러 보관소가 있고 OBSIDIAN_VAULT가 설정되지 않았습니다. 서버는 시작 시 stderr로 경고합니다. 하나를 고정하세요.

도구가 클라이언트에 나타나지 않음. 클라이언트의 MCP 로그를 확인하고 위의 절대 node 경로 문제를 확인하세요.

최신 상태 유지

git pull && npm install && npm run build

서버는 시작 시 최대 24시간에 한 번 업데이트를 확인하고 결과를 ~/.config/obsidian-cli-mcp/update-check.json에 캐시합니다. 오프라인에서는 조용히 실패하고 최신 버전이 있을 때 stderr에 한 줄을 출력합니다.

도구 (총 39개)

읽기 도구 (18개)

쓰기 도구 (16개)

모든 쓰기는 CLI를 통해 이루어집니다. 각각은 명시적인 file 또는 path 대상을 필요로 하며, 현재 활성 파일로 대체될 수 없습니다.

run_obsidian_command는 서버에서 가장 넓은 문입니다: 명령 팔레트의 모든 작업(커뮤니티 플러그인에 등록된 것 포함)에 접근할 수 있습니다. 의도적으로 노출되었으며 티어 2로 제한됩니다.

워크플로 도구 (4)

탈출구 (1)

MCP 리소스

리소스에 대한 클라이언트 지원은 다양하며, Claude Desktop은 현재 이를 표시하지 않습니다.

MCP 프롬프트

아키텍처

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

테스트는 전체 argv를 스캔하고 실패, 중단 또는 과도한 출력을 내보내도록 지시할 수 있는 스텁 바이너리에서 실행되므로, Obsidian이 설치되지 않은 상태에서도 전체 스위트가 통과됩니다:

npm test

지원

이슈 및 기능 요청: GitHub 이슈.

저자의 다른 프로젝트

• things-for-mac-mcp, Things 3용 자매 MCP 서버

라이선스

MIT