obsidian-mcp (Python)

로컬 Obsidian 볼트에 대한 읽기/쓰기 접근 권한을 LLM 클라이언트(예: Claude Desktop)에 제공하는 Python MCP(Model Context Protocol) 서버입니다. 직접 파일 시스템 접근 방식을 사용하며, Obsidian Local REST API 플러그인, HTTP, 인증 토큰이 필요 없습니다.

이 프로젝트는 obsidian-mcp(TypeScript)의 Python 포트로, 몇 가지 의도적인 수정과 단순화를 거쳐 기능적으로 동일합니다. 자세한 근거는 Plans/review-the-typescript-obsidian-mcp-parsed-shamir.md 및 ISA.md를 참조하세요.

경고: 이 서버는 볼트에 대한 읽기/쓰기 접근 권한을 가집니다. 사용 전에 노트를 백업하세요(예: git).

요구 사항

• Python 3.11+

• uv

• Obsidian 볼트(최소 한 번은 Obsidian에서 열린 디렉토리, 즉 .obsidian/app.json이 포함된 디렉토리)

• macOS 또는 Linux(Windows는 지원되지 않음 — ISA.md의 "Out of Scope" 참조)

Related MCP server: Obsidian MCP Server

설치 및 실행

uv sync
uv run obsidian-mcp /path/to/your/vault [/path/to/another/vault ...]

볼트 이름은 각 디렉토리의 기본 이름에서 자동으로 파생됩니다(소문자로 변환, 영숫자가 아닌 문자는 하이픈으로 대체, 중복 시 숫자 접미사 추가). 최대 10개의 볼트를 지원하며, 볼트 경로는 서로 중첩될 수 없습니다.

Claude Desktop 구성

claude_desktop_config.json을 편집하세요(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/py-obsidian-mcp", "obsidian-mcp", "/path/to/your/vault"]
    }
  }
}

도구

read-note, create-note, edit-note(append/prepend/replace/delete), delete-note(기본적으로 .trash/로 소프트 삭제), move-note, create-directory, search-vault(콘텐츠/파일명/태그 검색, 선택적 max_results), add-tags, remove-tags, rename-tag(볼트 전체, 계층 구조 보존), list-available-vaults.

또한 obsidian-vault:// 리소스 스킴(볼트 목록/정보)과 list-vaults 프롬프트도 제공합니다.

개발

uv sync --all-extras
uv run pytest -q
uv run ruff check src tests

보안 참고 사항

• 모든 도구는 대상 경로가 볼트 내에 유지되는지 검증합니다(src/obsidian_mcp/utils/path_safety.py). 심볼릭 링크 인식 검사도 포함됩니다.

• 원본 TypeScript 버전에는 이 포함 검사가 사실상 no-op이 되는 확인된 버그가 있었습니다(비동기 검증 함수가 await 없이 호출됨). 이 포트의 경로 안전 함수는 모두 동기식이므로 이러한 유형의 버그가 구조적으로 발생할 수 없습니다.