Obsidian MCP Server

obsidian-mcp-server는 Model Context Protocol(MCP)을 구현한 서버로, 로컬 Obsidian vault의 문서들을 AI 에이전트나 외부 애플리케이션에서 쉽게 탐색하고 관리할 수 있도록 강력한 도구 API를 제공합니다.

Obsidian Vault를 이용해 AI가 활용 가능한 지식 베이스(Knowledge Base)로 확장하여 사용할 수 있게끔 하고 문서 검색, 요약, 정리와 같은 부가적인 작업을 자동화하여 사용자가 핵심적인 "글쓰기 활동"에만 집중할 수 있는 환경을 구축하고자 제작했습니다.

핵심 아키텍처

본 서버는 VaultManager와 Indexer를 중심으로 구축되어 대규모 Vault에서도 높은 성능과 메모리 효율성을 보장합니다.

Indexer 기반 검색: 서버 시작 시 가벼운 역 인덱스(Inverted Index)를 생성하여 키워드 검색 시 거의 즉각적인 결과를 반환합니다(O(1)). 전체 파일 내용을 메모리에 상주시키지 않아 메모리 사용량을 최소화합니다.
VaultManager: Vault 내의 모든 문서를 효율적으로 관리하며, 파일 시스템과 상호작용하여 문서의 생성, 수정, 삭제를 처리합니다.

주요 기능

고급 문서 탐색: vault 도구를 통해 키워드 검색, 전체 목록 조회, 특정 문서 읽기, 통계 분석 등 다양한 탐색 기능을 제공합니다.
AI 기반 속성 생성: generate_property 도구는 문서 본문을 분석하여 title, tags, summary 등 적절한 frontmatter 속성을 자동으로 생성합니다.
안전한 속성 업데이트: write_property 도구를 사용하여 생성된 속성을 기존 frontmatter와 병합하여 파일에 안전하게 기록합니다.
첨부 파일 자동 정리: organize_attachments 도구는 문서와 연결된 첨부 파일(예: 이미지)을 자동으로 감지하여 문서 제목에 맞는 폴더로 이동시키고 링크를 업데이트합니다.
통합 워크플로우: create_document_with_properties와 같은 도구를 통해 문서 분석부터 속성 생성, 파일 업데이트까지의 전체 과정을 단일 명령으로 실행합니다.
신뢰성 및 테스트: vitest를 사용한 End-to-End 테스트와 GitHub Actions 기반의 CI/CD 파이프라인을 통해 서버의 안정성과 각 도구 API의 응답 스키마를 검증합니다.

도구 API

obsidian-mcp-server는 MCP 클라이언트를 통해 호출할 수 있는 다음과 같은 도구들을 제공합니다.

`vault`

Vault 내 문서를 탐색하고 분석하는 핵심 도구입니다. action 파라미터를 통해 다양한 기능을 수행할 수 있습니다.

list_all: Vault 내 모든 문서의 목록과 메타데이터를 반환합니다.
search: 키워드를 기반으로 문서 제목, 내용, 태그를 검색합니다.
read: 특정 파일의 내용을 읽고 frontmatter와 본문을 반환합니다.
stats: Vault 내 모든 문서의 통계(단어, 글자 수 등)를 제공합니다.

`generate_property`

문서 경로(filePath)를 입력받아 해당 문서의 내용을 분석하고, AI가 추천하는 frontmatter 속성을 생성하여 반환합니다.

`write_property`

파일 경로(filePath)와 JSON 형식의 속성(properties)을 입력받아, 해당 파일의 frontmatter를 업데이트합니다.

`create_document_with_properties`

문서 분석, 속성 생성, 파일 업데이트의 전 과정을 한 번에 처리하는 통합 도구입니다.

`organize_attachments`

키워드로 문서를 찾아 해당 문서에 연결된 모든 첨부 파일을 images/{문서 제목} 폴더로 이동시키고, 문서 내의 링크를 자동으로 업데이트합니다.

설치 및 사용

MCP 클라이언트 설정

MCP를 지원하는 AI 도구(Claude Desktop, Gemini 등)의 설정 파일에 다음 구성을 추가하세요.

Claude Desktop

claude_desktop_config.json 파일에 추가해야할 내용:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server"],
      "env": {
        "VAULT_DIR_PATH": "/absolute/path/to/your/obsidian/vault"
      }
    }
  }
}

Gemini

gemini_config.json 파일에 추가해야할 내용:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server"],
      "env": {
        "VAULT_DIR_PATH": "/absolute/path/to/your/obsidian/vault"
      }
    }
  }
}

설정 확인사항

Vault 경로: VAULT_DIR_PATH에는 반드시 절대 경로를 입력해야 합니다.

// ✅ 올바른 예시
"VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
"VAULT_DIR_PATH": "C:\\Users\\username\\Documents\\MyVault"  // Windows
"VAULT_DIR_PATH": "/mnt/c/Users/username/Documents/MyVault"  // WSL

// ❌ 잘못된 예시
"VAULT_DIR_PATH": "~/Documents/MyVault"  // 상대 경로 사용 불가
"VAULT_DIR_PATH": "./vault"              // 상대 경로 사용 불가

Node.js 요구사항: Node.js 22 이상이 설치되어 있어야 합니다.
```
node --version  # v22.0.0 이상 확인
```
설정 적용: 설정 파일 저장 후 AI 도구를 재시작하면 MCP 서버가 자동으로 연결됩니다.

수동 실행 (테스트용)

터미널에서 직접 서버를 실행하여 테스트할 수도 있습니다:

# 환경 변수 설정 후 실행
VAULT_DIR_PATH=/path/to/vault npx -y @sunub/obsidian-mcp-server

# 또는 명령줄 인자로 경로 지정
npx -y @sunub/obsidian-mcp-server --vault-path /path/to/vault

테스트

vitest를 사용한 End-to-End 테스트:

# 테스트 실행
npm test

# Watch 모드
npm run test:watch

코드 품질

# 포맷팅
npm run format

# 린팅
npm run lint

# 전체 체크 (포맷팅 + 린팅)
npm run check

CI/CD

이 프로젝트는 GitHub Actions를 사용하여 CI/CD 파이프라인을 구축했습니다:

빌드: TypeScript 컴파일 및 빌드 검증
린트: Biome를 사용한 코드 품질 검사
테스트: Vitest를 통한 E2E 테스트
배포: 태그 푸시 시 자동으로 npm에 배포

라이선스

ISC License

sunub-obsidian-mcp-server

Documentation