Obsidian AI 위키 구축: 원본 폴더부터 MCP 검증까지

Obsidian AI 위키를 만든다고 하면 플러그인부터 떠올리기 쉽습니다. 실제로 해보면 먼저 정해야 할 것은 플러그인이 아니라 원본 폴더, 검증 기준, AI가 읽을 범위입니다.

저는 기존 Markdown 문서 폴더를 Obsidian vault로 열고, 문서 구조 검사와 MCP 연결을 붙여 운영형 위키로 바꿨습니다. 당시 검증에서는 51개 노트와 8개 폴더를 확인했고 orphan 문서는 0개였습니다. readiness 검사를 보강한 뒤에는 관리 대상 25개가 READY에 도달했습니다. 이 숫자는 특정 시점의 점검 결과이며, 제품의 일반 성능 수치가 아닙니다.

완성된 구조는 아래와 같습니다.

기존 Markdown 문서
→ Obsidian vault로 열기
→ 링크·메타데이터·민감정보 검사
→ MCP resource로 필요한 문서만 노출
→ AI 클라이언트에서 검색·요약
→ 변경은 검토와 별도 승인 뒤 반영

1. 기존 Markdown 폴더를 vault로 엽니다

Obsidian 공식 문서에서 vault는 로컬 파일 시스템의 폴더입니다. 노트는 Markdown 형식의 일반 텍스트 파일로 저장되므로 Obsidian 밖의 편집기와 파일 도구에서도 다룰 수 있습니다.

이미 문서가 있다면 새 vault를 만들고 복사하기보다 Open folder as vault로 기존 폴더를 여는 편이 안전합니다. 이렇게 하면 자동화가 쓰는 원본 경로와 사람이 보는 위키가 갈라지지 않습니다.

확인할 항목은 세 가지입니다.

Obsidian 데스크톱 앱에서 폴더가 실제로 열리는가
내부 링크를 눌렀을 때 목표 노트로 이동하는가
다른 도구가 파일을 수정했을 때 Obsidian에 갱신되는가

vault 안에 또 다른 vault를 중첩하지 않습니다. 내부 링크의 기준점이 달라져 링크 갱신이 꼬일 수 있습니다. .obsidian 폴더에는 테마, 단축키, 플러그인처럼 vault별 설정이 들어가므로 콘텐츠와 구분해서 관리합니다.

2. 문서마다 최소 운영 메타데이터를 둡니다

폴더를 열었다고 운영 가능한 위키가 되는 것은 아닙니다. 각 프로젝트 노트에 최소한 아래 항목이 있어야 다음 사람이 이어받을 수 있습니다.

필드	역할
`status`	진행 중, 보류, 완료 상태
`owner`	다음 판단 책임자
`next_action`	바로 실행할 다음 작업
`source`	사실을 확인할 원문 또는 시스템
`updated_at`	내용의 기준 시점

저는 최상위 인덱스에서 모든 프로젝트 노트로 들어갈 수 있게 하고, 역으로 연결되지 않은 orphan 문서를 검사했습니다. 문서 수보다 중요한 것은 “현재 상태와 다음 행동을 어디서 확인하는가”가 한곳으로 모이는 것입니다.

3. READY를 느낌이 아니라 검사 결과로 만듭니다

초기 검사는 문서 길이 비율에 너무 의존했습니다. 긴 원문을 많이 복사한 노트가 좋은 점수를 받고, 짧지만 핵심 상태가 분명한 노트가 낮은 점수를 받을 수 있었습니다.

그래서 readiness를 다음 구조로 바꿨습니다.

필수 메타데이터가 있는가
상위 인덱스와 연결되는가
깨진 내부 링크와 orphan 문서가 없는가
큰 원문은 복사 대신 archive 또는 reference로 보존되는가
민감정보 검사를 통과했는가
export 전에 dry-run을 통과했는가

READY는 자동 승격 버튼이 아닙니다. 검사를 통과했다는 체크포인트입니다. 실제 반영은 경고 내용을 읽고, 변경 범위를 확인하고, 되돌릴 수 있는 상태에서 진행해야 합니다.

4. MCP에서는 문서를 resource로 먼저 노출합니다

MCP 서버를 붙일 때 처음부터 쓰기 도구를 많이 만들 필요는 없습니다. 공식 MCP 명세에서 resource는 파일이나 데이터처럼 모델에 문맥을 제공하는 단위이고, tool은 외부 시스템을 조회하거나 변경하는 실행 함수입니다.

Obsidian 위키에는 읽기부터 붙이는 편이 안전합니다.

resources/list
→ AI가 읽을 수 있는 노트 목록

resources/read
→ 선택한 노트의 Markdown 본문

그다음 정말 필요한 경우에만 검색, 인덱스 재생성, 상태 변경 같은 tool을 추가합니다. resource URI는 vault 경계 밖으로 빠져나가지 못하게 검증하고, 비공개 폴더와 자격 증명 파일은 목록 단계에서 제외해야 합니다. 쓰기 tool은 입력값, 대상 파일, 승인 여부를 실행 전에 보여주는 편이 좋습니다.

5. 통합 MCP 서버는 경계를 줄이는 쪽으로 설계합니다

처음에는 위키 전용 기능과 다른 자동화 기능을 각각 별도 서버로 붙였습니다. 실제 운영에서는 클라이언트마다 설정 파일과 권한을 따로 관리해야 해 점검 지점이 늘었습니다.

그래서 연결 지점은 하나로 모으되 내부 역할은 분리했습니다.

wiki resource: 검증된 Markdown 읽기
search tool: 허용된 범위 안에서 제목·본문 검색
status tool: readiness와 검사 결과 조회
write tool: 기본 비활성화, 승인된 작업에서만 사용

“서버 하나”가 “권한 하나”를 뜻해서는 안 됩니다. 읽기와 쓰기, 공개 문서와 비공개 문서, 조회와 승격의 경계는 서버 안에서도 따로 유지해야 합니다.

6. 앱에서 열어 보는 단계가 빠지면 안 됩니다

당시 가장 큰 누락은 문서 구조는 있었지만 Obsidian 데스크톱 앱에서 실제 vault를 열어보지 않았다는 점이었습니다. 앱을 설치하고 기존 폴더를 등록한 뒤에야 링크 이동, 탐색 구조, 사람이 읽을 때의 문제를 확인할 수 있었습니다.

자동 검사와 실제 사용 화면은 서로 대체하지 못합니다.

스크립트는 깨진 링크와 누락 필드를 잘 찾습니다.
Obsidian 앱은 탐색 순서와 문서 가독성을 보여줍니다.
MCP 클라이언트는 AI가 필요한 문맥을 실제로 읽는지 보여줍니다.

세 화면을 각각 확인해야 “파일은 있지만 아무도 못 쓰는 위키”를 피할 수 있습니다.

7. 동기화와 백업을 구분합니다

Obsidian은 노트를 기본적으로 로컬에 저장합니다. 여러 기기 동기화는 편리하지만 동기화 자체가 백업은 아닙니다. 한 기기에서 삭제하거나 손상된 내용이 다른 기기에도 전파될 수 있기 때문입니다.

운영용 vault에는 별도 백업을 둡니다.

주로 사용하는 한 기기를 백업 기준 기기로 정합니다.
vault를 다른 저장 위치로 단방향 복사합니다.
복원 테스트로 Markdown 파일과 첨부파일이 함께 돌아오는지 확인합니다.
Git을 쓴다면 자격 증명과 개인 설정 파일이 추적되지 않는지 확인합니다.

어느 화면에서 막혔는지로 점검을 시작합니다

Obsidian에서도 목표 노트를 못 찾는 경우: 원본 폴더를 제대로 열었는지와 인덱스·내부 링크부터 봅니다.
앱에서는 보이는데 AI 클라이언트에서는 안 보이는 경우: 허용 폴더, resource 목록, 선택한 URI의 읽기 결과를 차례로 확인합니다.
읽히지만 내용이 오래된 경우: 노트의 source와 updated_at을 대조하고 현재 상태를 다시 확인합니다. 연결 성공과 내용의 최신성은 다른 항목입니다.

MCP Resources 명세는 문맥을 어떻게 선택하고 포함할지 호스트 애플리케이션이 결정한다고 설명합니다. 서버에서 목록 조회가 됐다는 것만으로 AI의 답변에 해당 문서가 실제 포함됐다고 보지는 않습니다. 그래서 위의 앱·문서·클라이언트 검사를 나눴습니다.

읽을 문서는 있는데 상태 설명이 충돌한다면 AI 기억과 프로젝트 보드의 근거를 맞춘 사례처럼 확인 환경과 시각부터 구분합니다. 위키 구축 자체가 상태 검증을 대신하지는 않습니다.

자주 실패하는 지점

문서를 많이 넣으면 자동으로 좋은 위키가 된다

문서 수가 늘수록 orphan, 중복 상태, 오래된 next action도 함께 늘 수 있습니다. 인덱스와 readiness 검사가 먼저입니다.

AI가 vault 전체를 읽게 하면 검색이 쉬워진다

범위가 넓으면 비공개 문서와 오래된 정보까지 섞입니다. 허용 폴더와 resource 목록을 먼저 제한해야 합니다.

READY면 바로 원본에 반영해도 된다

READY는 구조 검사 결과일 뿐입니다. dry-run, 변경 내용 검토, 백업, 승인 순서가 남아 있습니다.

동기화 중이니 백업도 됐다

동기화와 복구용 사본은 역할이 다릅니다. 별도 위치의 단방향 백업이 필요합니다.

운영 체크리스트

[ ] 기존 폴더를 Obsidian 앱에서 실제로 열었다
[ ] 상위 인덱스에서 모든 운영 노트로 이동할 수 있다
[ ] status, owner, next action, source, updated_at이 있다
[ ] 깨진 링크와 orphan 문서 검사를 통과했다
[ ] MCP resource가 허용한 폴더만 노출한다
[ ] 쓰기 tool은 기본적으로 꺼져 있거나 승인 절차가 있다
[ ] 동기화와 별도의 백업·복원 절차가 있다
[ ] READY 이후에도 dry-run과 사람 검토를 거친다

관련된 검증·복구 구조는 루프 엔지니어링 가이드에서 더 자세히 설명했습니다.

공식 문서

정보 기준일: 2026-09-03
재편집 범위: 공개 페이지의 구조·체크리스트·공식 문서 링크와 미검증 범위를 다시 점검했습니다. 2026년 4월 당시의 수치와 구현 결과를 새 벤치마크처럼 확장하지 않았습니다.
경험 범위: 2026-04-27~28에 기존 Markdown 폴더를 Obsidian vault와 MCP 기반 위키로 구성하고, 앱·문서 구조·검사 결과를 직접 확인한 사례
협찬·광고·원고료: 없음

편집 메모: 2026-09-10. 당시 경험과 수치를 보존하고 판단 기준과 관련 글 연결을 보완했습니다. 새 설치·성능 시험이나 현재 운영 상태의 재검증을 한 것은 아닙니다.