Obsidian Vault MCP

AI 에이전트에게 로컬 Obsidian 볼트에 대한 통제된 접근을 제공하는 HTTP Model Context Protocol 서버입니다.

마크다운 노트의 나열, 읽기, 검색, 생성, 업데이트, 이름 변경, 신중한 삭제가 필요한 에이전트 런타임(Grok 봇, Claude, OpenClaw, 사용자 정의 MCP 클라이언트)을 위해 제작되었습니다.

기능

• 스트리밍 가능한 HTTP MCP 엔드포인트(/mcp)

• Bearer / API 키 인증

• 전체 볼트 모드(ALLOWLIST=*) 또는 폴더 허용 목록

• 읽기 도구: list_notes, list_folder, read_note, search_notes

• 쓰기 도구: create_note, append_note, update_note, create_folder, rename_path, delete_path

• .obsidian, .git, dotfile, .env, 키 자료 차단

• 원자적 쓰기 + 크기 제한

• 운영용 상태 엔드포인트: /healthz

Related MCP server: obsidian-autom8

빠른 시작

npm install
export VAULT_ROOT="/absolute/path/to/your/vault"
export BEARER_TOKEN="$(openssl rand -hex 32)"
export ALLOWLIST="*"
export WRITE_ALLOWLIST="*"
export MODE="read-write"
export PORT=8790
export BIND=127.0.0.1
export PUBLIC_BASE="http://127.0.0.1:8790"
npm start

상태 확인:

curl -s http://127.0.0.1:8790/healthz | jq .

환경 변수

허용되는 인증 헤더:

• Authorization: Bearer <token>

• X-Api-Key: <token>

• X-Obsidian-Token: <token>

MCP 도구

읽기

• list_notes — 마크다운 경로 나열(선택적 접두사)

• list_folder — 파일/디렉터리 나열(recursive 선택 사항)

• read_note — 노트 하나 + 간단한 frontmatter 읽기

• search_notes — 대소문자를 구분하지 않는 부분 문자열 검색

쓰기(MODE=read-write일 때)

• create_note — 마크다운 노트 생성(overwrite 선택 사항)

• append_note — 노트에 추가

• update_note — 전체 노트 교체

• create_folder — 폴더 트리 생성

• rename_path — 파일 또는 폴더 이름 변경/이동

• delete_path — 마크다운 파일 또는 폴더 삭제(비어 있지 않은 경우 recursive)

안전:

• .obsidian, .git, 숨김 경로, .env, 키 파일을 절대 제공하지 않음

• 쓰기는 .md / .markdown / .txt로 제한

• 보호된 최상위 구조 앵커는 일괄 삭제할 수 없음

• 비밀은 볼트에 있어서는 안 되며, 이 서버 구성은 git에 커밋해서는 안 됨

리버스 프록시 예시(nginx)

location ^~ /obsidian-mcp/ {
  proxy_pass http://127.0.0.1:8790/;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header Authorization $http_authorization;
  proxy_set_header X-Api-Key $http_x_api_key;
  proxy_buffering off;
}

HTTPS로만 노출하고 Node 프로세스에서 BIND=127.0.0.1을 유지하세요.

Grok / 에이전트 프롬프트 스니펫

You have MCP tools for an Obsidian vault via obsidian-vault-mcp.

Rules:
1. First call list_folder path="" to see top-level structure.
2. Read OBSIDIAN-STRUCTURE.md if present before reorganizing.
3. Prefer append_note for changelogs; do not rewrite history casually.
4. Create notes only as .md under clear topic folders.
5. Never store secrets, tokens, private keys, or .env values.
6. Use search_notes before creating near-duplicate docs.
7. Use rename_path to organize; use delete_path only for clearly obsolete drafts.

보안 참고 사항

• 이 서버는 강력합니다. BEARER_TOKEN을 비밀번호처럼 취급하세요.

• 프로덕션에서는 네트워크 격리 + 리버스 프록시 인증을 선호하세요.

• 전체 볼트 쓰기 모드는 신뢰할 수 있는 내부 에이전트를 위한 의도적 설계입니다. 신뢰도가 낮은 봇에는 WRITE_ALLOWLIST를 강화하세요.

• .env, 토큰, 실제 볼트 내용을 커밋하지 마세요.

라이선스

MIT