Obsidian Vault API — Docker

Obsidian Vault API의 Docker 호환 버전입니다. Obsidian 볼트를 MCP 서버로 노출합니다 — Obsidian 데스크톱 앱이 필요 없습니다. 모든 서버 또는 NAS에서 24/7 실행됩니다.

원본 플러그인은 Obsidian 내부에서 실행되며 이미지 처리를 위해 Obsidian API + Electron의 Canvas를 사용합니다. 이 버전은 Docker에서 독립형 Node.js 프로세스로 실행되며, 직접적인 fs 작업과 sharp를 사용하여 이미지 크기를 조정합니다. 원본의 13개 MCP 도구가 모두 보존됩니다.

빠른 시작

docker-compose (권장)

services:
  vault-api:
    build: .
    container_name: obsidian-vault-api
    restart: unless-stopped
    ports:
      - "2768:2768"
    volumes:
      - /path/to/your/vault:/vault
      - vault-api-data:/data
    environment:
      - VAULT_API_KEY=your-secret-key-here

volumes:
  vault-api-data:

docker compose up -d

docker run

docker run -d \
  --name obsidian-vault-api \
  -p 2768:2768 \
  -v /path/to/your/vault:/vault \
  -v vault-api-data:/data \
  -e VAULT_API_KEY=your-secret-key-here \
  ghcr.io/alexandre1116/obsidian-vault-api-docker:latest

웹 UI

컨테이너를 시작한 후 브라우저를 열고 다음으로 이동합니다:

http://localhost:2768/

대시보드에서 다음을 할 수 있습니다:

• 서버 상태 보기 (실행 중/중지됨, 포트, 볼트 이름)

• 구성 편집 (포트, 바인드 주소, 허용된 명령) — 변경 사항은 /data/config.json에 저장되며 재시작 후에도 유지됩니다

• API 키 재생성 — 새 시크릿을 생성하며, 클라이언트 재연결이 필요합니다

• MCP 서버 재시작 / 중지 — 컨테이너를 중지하지 않고 수행

• 연결 정보 복사 — SSE URL, Claude Desktop JSON 구성, API 키

웹 UI 자체는 인증이 필요 없습니다 (구성 페이지이기 때문입니다). MCP 엔드포인트 (/sse, /message, /raw)는 API 키가 필요합니다.

구성

구성은 /data/config.json에 저장되며 컨테이너 재시작 후에도 유지됩니다. 환경 변수는 첫 부팅 시 초기 재정의 역할을 합니다 — 이후에는 구성 파일이 기준이 됩니다.

AI 클라이언트 연결

LM Studio / Open WebUI / SSE를 지원하는 모든 MCP 클라이언트

MCP 서버 URL 추가:

http://localhost:2768/sse?key=YOUR_API_KEY

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:2768/sse?key=YOUR_API_KEY"
    }
  }
}

또는 웹 UI 대시보드에서 JSON을 직접 복사합니다.

인증

다음 중 하나:

• 쿼리 매개변수: ?key=YOUR_API_KEY

• HTTP 헤더: X-Api-Key: YOUR_API_KEY

사용 가능한 도구

이미지 지원

큰 이미지는 sharp를 사용하여 자동으로 크기가 조정됩니다 (순수 Node.js, Electron 불필요):

NFS / 네트워크 마운트

서버는 모든 도구 호출 시 파일 시스템에서 파일을 새로 읽습니다 — 캐싱이 없습니다. NFS 마운트는 실시간으로 작동합니다:

volumes:
  - nfs-vault:/vault

volumes:
  nfs-vault:
    driver: local
    driver_opts:
      type: nfs
      device: ":/path/on/nfs"
      o: addr=10.0.0.1,nfsvers=4

상태 확인

curl http://localhost:2768/health

공개적으로 { "status": "ok", "version": "1.1.0" }를 반환합니다. 인증된 요청은 vault, port, sessions도 반환합니다.

소스에서 빌드

git clone https://github.com/Alexandre1116/Obsidian-Vault-API-Docker
cd Obsidian-Vault-API-Docker
docker compose build
docker compose up -d

또는 Docker 없이:

npm install
npm run build
VAULT_PATH=/path/to/vault VAULT_API_KEY=secret npm start

원본 플러그인과의 차이점

라이선스

CC BY-NC-SA 4.0 — 원본 프로젝트와 동일합니다.