local-docs-mcp

ローカルPCのドキュメントを読み、要約と整理を支援する個人用MCPサーバーです。 PDF・Word・Excel・PowerPoint・ハングル・Markdown・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

整理基準は4つです。

安全装置

1. パス封鎖 — すべての入力パスをresolve()した後、許可ルート内か確認します。..、シンボリックリンク、ドライブ移動はすべてここでブロックされます。

2. 書き込み封鎖 — 保存は出力フォルダ内でのみ可能です。読み取りルートには書き込みません。

3. 除外フォルダ — .git node_modules .venv AppDataなどは走査も読み取りもしません。

4. 承認トークン — プレビュー内容のハッシュです。内容が1文字でも変わるとトークンが壊れ、保存・整理が拒否されます。ただし、トークンは技術的な整合性のみ保証し、ユーザーの承認に代わるものではありません。

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は行わず、警告のみ残します。

• Excelの日付セルは内部シリアル番号で表示される場合があります。

• .hwp（バイナリ）は最善抽出です。表・脚注の順序が原文と異なる場合があります。

• 画像内の文字はどの形式でも読み取りません。

ライセンス

MIT — LICENSE