obsidian-cli-mcp

obsidian-cli-mcp는 공식 Obsidian CLI를 위한 MCP 서버입니다. Obsidian 볼트 검색, 노트, 작업, 파일, 링크 및 네이티브 Canvas 작업을 MCP 클라이언트에 노출합니다. 이 서버는 Obsidian을 대체하지 않습니다. CLI는 실행 중인 Obsidian 데스크톱 앱에 요청을 전달합니다.

기본 전송 방식은 로컬 stdio입니다. 원격 Streamable HTTP는 고급 기능으로, 별도로 보안을 설정해야 하며 로컬 사용에는 필요하지 않습니다.

요구 사항

• macOS에 Obsidian Desktop이 설치되어 실행 중이어야 합니다.

• Obsidian에서 공식 Obsidian CLI를 활성화해야 합니다: 설정 → 일반 → 명령줄 인터페이스에서 obsidian을 PATH에 등록하세요.

• 게시된 패키지를 실행하려면 Node.js 18 이상이 필요합니다. Bun은 이 소스 저장소를 빌드하거나 개발할 때만 필요합니다.

이 프로젝트는 데스크톱 CLI가 필요합니다. obsidian-headless는 지원하지 않습니다. MCP 서버를 사용하는 동안 Obsidian 앱이 열려 있어야 합니다.

먼저 Obsidian 쪽을 확인하세요:

command -v obsidian
obsidian version
obsidian vault

npm으로 빠른 시작

게시된 v0.4.1 패키지를 어느 디렉토리에서든 시작하세요:

npx --yes --package=@dariuscodes/obsidian-cli-mcp@0.4.1 obsidian-cli-mcp

이 명령은 stdio를 통해 MCP를 사용하며 MCP 클라이언트를 기다립니다. 의도적으로 프로토콜 데이터를 터미널에 출력하지 않습니다. 진단 정보는 stderr로 전송됩니다.

소스 저장소를 사용하는 경우:

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

로컬 기본 설정에는 볼트 이름, 볼트 경로, 토큰, Cloudflare 계정, LaunchAgent 또는 구성 파일이 필요하지 않습니다. 서버는 Obsidian이 공식 CLI를 통해 노출하는 활성 볼트를 사용합니다.

MCP 클라이언트 연결

mcpServers 구성을 허용하는 클라이언트의 경우 npm 명령을 사용하세요:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/obsidian-cli-mcp@0.4.1",
        "obsidian-cli-mcp"
      ]
    }
  }
}

클라이언트가 셸 PATH를 상속하지 않는 경우 npx를 command -v npx로 출력된 절대 경로로 바꾸세요. 소스 저장소를 사용하는 경우 command: "node" 및 args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"]를 사용하세요.

MCP 구성을 변경한 후 클라이언트를 다시 시작하세요. 첫 번째 유용한 순서는 다음과 같습니다:

1. 볼트에 존재해야 하는 쿼리로 vault_search를 호출하세요. 예: { "query": "meeting", "limit": 10 }.

2. 반환된 경로 중 하나를 note_read에 전달하세요. 예: { "path": "<vault_search가 반환한 경로>" }.

3. 적용하기 전에 안전한 노트 변경을 미리 보세요:

   {
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }

   이것은 note_create 호출입니다. 볼트를 변경하지 않고 계획된 작업과 정확한 CLI 명령을 반환합니다. 계획을 검토한 후에만 dryRun: false를 사용하세요. dryRun은 미리 보기일 뿐, 권한 경계가 아닙니다.

4. Canvas의 경우 네이티브 Canvas 파일과 텍스트 노드 하나를 미리 보세요:

   {
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }

   이것은 canvas_create 호출입니다. 계획을 검토한 후 파일을 만들려면 dryRun: false로 호출하세요. 이후 canvas_read로 네이티브 .canvas JSON을 검사하세요. Canvas 도구는 알 수 없는 필드를 보존하고, 노드/엣지 참조를 검증하며, 임의의 eval을 요구하지 않습니다.

구성 및 안전한 기본값

빈 구성 또는 누락된 구성은 일반 Obsidian 볼트에서 사용할 수 있습니다. 선택적 .obsidianmcprc.yaml은 서버 작업 디렉토리에서 발견됩니다. 작업 디렉토리를 예측할 수 없는 클라이언트의 경우 OBSIDIAN_MCP_CONFIG를 명시적인 구성 파일 경로로 설정하세요.

기본 정책은 의도적으로 로컬 및 제한적입니다:

• v0.4.0 서버는 일반적인 obsidian_eval 도구를 노출하지 않습니다. eval.enabled는 기본적으로 false이며, 몇 가지 안전한 작업에 사용되는 내부 고정 eval 스니펫은 사용자 제공 JavaScript 탈출구가 아닙니다.

• 임의 로컬 파일에서의 가져오기는 imports.allowedRoots가 명시적으로 구성될 때까지 비활성화됩니다. URL은 절대 가져오지 않습니다.

• .obsidian, .git, .trash, .Trash, Trash 및 .DS_Store 경로 세그먼트는 기본적으로 차단됩니다. 더 좁은 볼트 영역을 위해 paths.allow를 추가하고 더 민감한 콘텐츠에 대해 프로젝트별 paths.deny 접두사를 추가하세요.

• 변경 작업은 dryRun을 노출합니다. file_delete는 confirm: true가 필요하며 note_delete는 기본적으로 Obsidian 휴지통을 사용합니다. 영구 삭제는 명시적인 delete.mode: hard 구성이 필요합니다.

• Git 자동 커밋은 기본적으로 꺼져 있습니다.

읽기 전용 프리셋

MCP 클라이언트가 볼트만 검사해야 하는 경우 명시적 허용 목록을 사용하세요:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - file_read_binary_metadata
    - canvas_read

안전한 로컬 프리셋

기본값은 안전한 로컬 가드레일이 있지만 읽기 전용은 아닙니다. 삭제, 파일 가져오기, 파일 수명 주기 작업 및 임의 평가를 생략하면서 일반 노트 편집과 Canvas 생성을 허용하는 명시적 안전 로컬 표면의 경우:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - canvas_read
    - canvas_create
    - canvas_upsert_nodes
    - canvas_upsert_edges
    - canvas_add_node
    - canvas_add_edge
    - canvas_auto_layout
    - canvas_open
    - note_create
    - note_append
    - note_set_frontmatter
    - note_replace_range
    - note_insert_at
    - note_replace
    - note_insert
    - daily_open
    - daily_append
    - task_create
    - task_update
delete:
  mode: trash
eval:
  enabled: false
imports:
  allowedRoots: []

전체 신뢰 로컬 프리셋

tools.allow를 생략하면 기본 보호 경로, 휴지통 삭제, 비활성화된 가져오기 및 비활성화된 obsidian_eval을 유지하면서 전체 내장 도구 표면을 노출합니다. 가져오기가 필요한 경우 전용 로컬 소스 디렉토리만 구성하세요:

imports:
  allowedRoots:
    - /absolute/path/to/approved-imports
  maxBytes: 26214400
  collision: increment
delete:
  mode: trash
eval:
  enabled: false

모든 필드는 docs/configuration.md를 참조하고 노트 구성 프리셋은 examples/를 참조하세요.

로컬 stdio 대 원격 HTTP

로컬 stdio는 MCP 클라이언트에서 직접 하나의 서버 프로세스를 시작합니다. 권장 설치 방법입니다: 수신 소켓, 원격 인증, Cloudflare 설정 또는 공개 엔드포인트가 없습니다.

Streamable HTTP는 로컬 stdio를 사용할 수 없는 클라이언트를 위한 선택적 고급 모드입니다. 루프백에만 바인딩되며 Cloudflare Access JWT 검증 또는 강력한 기능 토큰 없이는 시작을 거부합니다. TLS, 인증된 역방향 프록시 또는 터널 뒤에 배치하세요. 0.0.0.0에 바인딩하지 마세요. 일반적인 고급 설정 및 보안 절충에 대해서는 docs/remote-cloudflare.md를 참조하세요.

도구 표면

기본 서버는 42개의 일반 도구를 제공합니다:

• 읽기: vault_search, note_read, note_list, vault_tags, unresolved_links, tasks_list, note_diff, backlinks_get, outlinks_get, file_read_binary_metadata, canvas_read.

• 쓰기 및 워크플로: note_create, note_append, note_set_frontmatter, daily_open, daily_append, note_replace_range, note_insert_at, note_replace, note_insert, task_create, task_update, note_transition.

• 파일 및 첨부 파일: file_import, attachment_import, note_attach, attachment_embed, file_move, file_rename, file_delete, note_rename, note_move, folder_create, note_delete.

• Canvas: canvas_create, canvas_upsert_nodes, canvas_upsert_edges, canvas_remove, canvas_open, canvas_add_node, canvas_add_edge, canvas_auto_layout.

모든 변경 도구는 dryRun을 허용합니다. 도구 주석은 호환되는 MCP 클라이언트를 위해 읽기 전용 및 파괴적 작업을 식별합니다.

제한 사항 및 보안

Obsidian Desktop이 실행 중이어야 하고, 공식 CLI가 활성화되어 있어야 하며, 활성 볼트가 해당 데스크톱 세션에서 사용 가능해야 합니다. 이 서버는 샌드박스가 아니며 obsidian-headless를 지원하지 않습니다.

볼트 콘텐츠는 신뢰할 수 없는 데이터입니다. 노트, Canvas 텍스트, 작업 텍스트 및 검색 결과에는 프롬프트 주입 지침이 포함될 수 있습니다. MCP 클라이언트는 이를 데이터로 취급하고 도구가 반환했다는 이유만으로 볼트 내부에서 발견된 지침을 절대 따르지 않아야 합니다. 도구 출력에는 민감한 볼트 콘텐츠도 포함될 수 있으므로 신뢰하는 클라이언트만 연결하세요.

원격 HTTP, 가져오기, 하드 삭제 또는 광범위한 변경 허용 목록을 활성화하기 전에 SECURITY.md를 읽으세요. 보안 문제는 해당 문서에 설명된 대로 비공개로 보고하세요.

개발 및 CI

소스 저장소는 Bun을 사용하고 게시된 bin은 Node에서 실행됩니다:

bun install
bun run typecheck
bun test
bun run build:schema
bun run build
bun run smoke:stdio
git diff --check
npm pack --dry-run --json

오프라인 stdio 스모크는 빌드된 패키지 진입점, MCP initialize, tools/list, 예상 도구 표면 및 obsidian_eval 부재를 검증합니다. 실제 Obsidian 스모크는 별도이며 Obsidian이 실행 중인 사용자 세션이 필요합니다:

OBSIDIAN_CLI_BINARY=obsidian \
  OBSIDIAN_MCP_CONFIG=/absolute/path/to/your/config.yaml \
  OBSIDIAN_MCP_VAULT="your-vault-name" \
  bun run smoke:live

GitHub Actions는 오프라인 게이트만 실행합니다. 호스팅 러너에서 Obsidian Desktop 또는 실제 볼트에 의존하지 않습니다.

라이선스

MIT