Obsidian MCP Local

VS Code + GitHub Copilot에 Obsidian 볼트를 노출하기 위한 Node.js + TypeScript 기반의 MCP 로컬 서버입니다.

이 서버는 볼트 내의 Markdown 노트를 읽고 쓰는 데 중점을 두고 stdio를 통한 로컬 사용을 위해 설계되었습니다.

기능

사용 가능한 도구

• search_notes(query)

  • 경로, 프런트매터 및 노트 내용에서 텍스트 검색

  • 짧은 발췌문과 함께 순위가 매겨진 결과 반환

• get_note(path)

  • 볼트에서 노트 열기

  • path, frontmatter, content 반환

• create_note(path, content, overwrite?)

  • 새 노트 생성

  • 선택적으로 기존 노트 덮어쓰기 가능

• append_to_note(path, content)

  • 기존 노트 끝에 내용 추가

• find_by_tag(tag)

  • 태그별로 노트 찾기

  • 프런트매터의 tags 및 내용 내 인라인 태그 지원

구현된 규칙

• 설정된 볼트 내부의 파일에만 액세스

• 다음 디렉토리 무시:

  • .obsidian

  • .git

  • node_modules

• .md 파일만 처리

• 기본 디렉토리 외부로의 액세스를 방지하기 위해 경로 정규화

프로젝트 구조

obsidian-mcp-local/
  package.json
  tsconfig.json
  README.md
  .vscode/
    mcp.example.json
  src/
    index.ts

사전 요구 사항

• Node.js 20+

• npm

• GitHub Copilot이 포함된 VS Code

• 로컬 Obsidian 볼트

설치

프로젝트 디렉토리에서:

npm install
npm run build

개발용:

npm run dev

컴파일된 버전 실행:

npm start

VS Code에서 사용하는 방법

1. 프로젝트 컴파일

npm install
npm run build

2. VS Code MCP 파일 조정

.vscode/mcp.example.json의 내용을 Copilot을 사용할 워크스페이스의 .vscode/mcp.json으로 복사합니다.

예시:

{
  "servers": {
    "obsidian-local-vault": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/caminho/para/obsidian-mcp-local/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "D:/Obsidian/Vault"
      }
    }
  }
}

3. 경로 업데이트

다음 경로를:

• C:/caminho/para/obsidian-mcp-local/dist/index.js

• D:/Obsidian/Vault

사용자의 실제 머신 경로로 교체하세요.

4. VS Code 재시작/새로고침

이후 Copilot이 MCP 서버를 감지해야 합니다.

Copilot Chat 사용 예시

• “내 볼트에서 .NET 관련 노트를 찾아줘”

• “knowledge/backend/dotnet.md 노트를 열어줘”

• “우리가 논의한 내용을 요약해서 inbox/ideias-mcp.md에 노트를 생성해줘”

• “daily/2026-04-06.md 노트 끝에 - testar MCP local 텍스트를 추가해줘”

• “#arquitetura 태그가 있는 노트를 찾아줘”

향후 개선 가능 사항

• append_under_heading

• [[wikilinks]] 파싱

• get_backlinks(note)

• 빠른 검색을 위한 SQLite 인덱스

• 쓰기용 폴더 화이트리스트 (inbox/, daily/, scratch/)

• 특정 폴더에 대한 쓰기 차단 설정

중요 참고 사항

• 이 프로젝트는 Obsidian이 열려 있을 필요가 없습니다.

• 볼트 파일에 직접 작동합니다.

• Obsidian과 VS Code 모두에서 쓰기를 활성화하는 경우, 동시성 제어는 사용자의 책임입니다.

• 현재 프로젝트는 볼트가 로컬 Markdown 폴더임을 가정합니다.

메인 파일

구현 위치:

• src/index.ts

라이선스

개인 사용 / 커스터마이징을 위한 초기 베이스.