local-docs-mcp

로컬 PC의 문서를 읽어 요약과 정리를 돕는 개인용 MCP 서버입니다. PDF·Word·엑셀·파워포인트·한글·마크다운·CSV 등을 텍스트로 뽑아 주고, 요약본 저장과 파일 정리를 승인 절차와 함께 처리합니다.

• 네트워크를 쓰지 않습니다. API 키가 필요 없습니다.

• 요약은 이 서버가 하지 않습니다. 원문을 정확히 뽑아 주면 요약은 Claude가 씁니다. (서버가 주는 machine_keypoints는 빈도 기반 기계 추출이며 요약이 아닙니다.)

• 허용한 폴더 밖은 읽지 못합니다. 파일을 옮기거나 저장할 때는 반드시 승인을 거칩니다.

지원 형식

.doc .xls .ppt(옛 이진 형식)는 읽지 않고 "x 붙은 형식으로 저장하라"고 안내합니다.

Related MCP server: Knowledge Assistant MCP

설치

Python 3.11 이상이 필요합니다.

python -m venv .venv && .venv/Scripts/pip install -e ".[formats,dev]"

macOS · Linux는 .venv/bin/pip을 씁니다. [formats]는 PDF용 pypdf와 .hwp(이진)용 olefile을 함께 설치하며, 없어도 나머지 형식은 동작합니다.

Claude Code에 등록

<PROJECT_DIR>는 이 저장소를 클론한 절대 경로, <HOME>은 사용자 홈 폴더입니다.

claude mcp add local-docs --scope user --env DOCS_MCP_ROOTS="<HOME>/Desktop;<HOME>/Documents" --env DOCS_MCP_OUTPUT="<HOME>/Desktop/docs-mcp-out" -- <PROJECT_DIR>/.venv/Scripts/python.exe -m docs_mcp.server

이 저장소 안에서만 쓰려면 .mcp.json.example을 .mcp.json으로 복사한 뒤 <PROJECT_DIR>와 <HOME>을 실제 경로로 바꾸세요. .mcp.json은 머신마다 경로가 달라 저장소에 추적하지 않습니다.

환경 변수

도구 11개

읽기 전용(R)과 쓰기(W)를 구분해 등록하므로 호스트가 승인 UI를 다르게 띄웁니다.

권장 흐름

list_roots
  → scan_documents          어떤 문서가 있는지
  → outline_document        긴 문서는 뼈대부터
  → read_document           원문을 근거로 확보 (필요하면 이어 읽기)
  → (Claude가 요약 작성)
  → preview_save_summary    저장 내용 확인
  → [사용자 승인]
  → save_summary

정리는 따로 진행합니다.

preview_organize   계획만 생성 — 파일은 하나도 건드리지 않음
  → [사용자가 계획 확인·승인]
  → apply_organize (기본 copy)
  → 문제가 있으면 undo_last_organize

정리 기준은 네 가지입니다.

안전 장치

1. 경로 봉쇄 — 모든 입력 경로를 resolve()한 뒤 허용 루트 안인지 확인합니다. .., 심볼릭 링크, 드라이브 이동 모두 여기서 막힙니다.

2. 쓰기 봉쇄 — 저장은 출력 폴더 안에서만 가능합니다. 읽기 루트에는 쓰지 않습니다.

3. 제외 폴더 — .git node_modules .venv AppData 등은 훑지도 읽지도 않습니다.

4. 승인 토큰 — 미리보기 내용의 해시입니다. 내용이 한 글자라도 달라지면 토큰이 깨져 저장·정리가 거부됩니다. 단, 토큰은 기술적 무결성만 보장하며 사용자 승인을 대신하지 않습니다.

5. 기본은 복사 — 원본 이동은 DOCS_MCP_ALLOW_MOVE=1이 있어야만 가능합니다.

6. 삭제하지 않음 — 되돌리기도 파일을 지우지 않고 _trash 폴더로 옮깁니다.

검증

.venv/Scripts/python.exe -m pytest -q

.venv/Scripts/python.exe scripts/smoke.py

.venv/Scripts/python.exe scripts/simulate.py

• pytest — 형식별 추출·경계 검사·승인 흐름 (단위)

• smoke.py — 실제 stdio로 initialize → tools/list → tools/call 확인

• simulate.py — 가상 문서 세트를 만들어 전체 흐름을 실제 MCP 연결로 재현합니다. 회의록·계약서·견적·발표자료·PDF·CP949 메모 등 가상 문서 12개를 만들고, 훑기 → 요약 저장 → 정리 → 되돌리기까지 진행하며 막혀야 할 일(루트 밖 읽기, 토큰 위조, 원본 이동)이 실제로 막히는지 확인합니다. 임시 폴더에서 돌고 끝나면 스스로 지웁니다. 결과를 남겨 보려면 폴더를 인자로 넘기세요.

한계

• 스캔 이미지 PDF는 텍스트가 없습니다. OCR은 하지 않고 경고만 남깁니다.

• 엑셀 날짜 셀은 내부 일련번호로 보일 수 있습니다.

• .hwp(이진)는 최선 추출입니다. 표·각주 순서가 원문과 다를 수 있습니다.

• 이미지 안의 글자는 어떤 형식에서도 읽지 않습니다.

라이선스

MIT — LICENSE