local-docs-mcp
local-docs-mcp
ローカルPCのドキュメントを読み、要約と整理を支援する個人用MCPサーバーです。 PDF・Word・Excel・PowerPoint・ハングル・Markdown・CSVなどをテキストに抽出し、要約の保存とファイル整理を承認手続きとともに処理します。
ネットワークは使いません。APIキーは不要です。
要約はこのサーバーが行いません。 原文を正確に抽出すれば、要約はClaudeが書きます。(サーバーが提供する
machine_keypointsは頻度ベースの機械抽出であり、要約ではありません。)許可したフォルダの外は読み取れません。ファイルを移動・保存する際は必ず承認を経ます。
対応形式
種類 | 拡張子 | 方式 |
文書 |
| ZIP+XML直接パース(タイトル・段落・表) |
ハングル |
| hwpxは基本サポート、 |
|
| |
プレゼン |
| スライド番号順+発表者ノート |
表 |
| シートごと、共有文字列の解釈 |
データ |
| 列名・行数を含む |
Web・メール |
| タグ除去、メールはヘッダー+本文 |
テキスト・コード |
| UTF-8/CP949/EUC-KR自動判別 |
.doc .xls .ppt(旧バイナリ形式)は読み取らず、「xの付いた形式で保存してください」と案内します。
Related MCP server: file-analysis
インストール
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はマシンごとにパスが異なるため、リポジトリでは追跡しません。
環境変数
変数 | 意味 | デフォルト値 |
| 読み取りを許可するフォルダのリスト( | デスクトップ・ドキュメント・ダウンロード |
| 要約と整理記録を書き込むフォルダ |
|
| 1ファイルの最大サイズ |
|
|
| 未設定(コピーのみ) |
ツール11個
読み取り専用(R)と書き込み(W)を区別して登録するため、ホストが承認UIを異なる形で表示します。
ツール | 機能 | |
R |
| 読み取り可能なフォルダ・対応形式・制限の確認 |
R |
| フォルダを走査してドキュメント一覧(種類・サイズ・更新日) |
R |
| 構造・タイトル・キーワード・代表文。全文を読む前の判断用 |
R |
| 本文抽出。セクションラベルと続き読みカーソルを提供 |
R |
| 複数ドキュメントの本文検索+根拠スニペット |
R |
| 複数ドキュメントを文字予算内で均等に抜粋 |
R |
| 保存する内容・パスのプレビュー+承認トークン発行 |
W |
| 承認された要約を出力フォルダに保存 |
R |
| 整理計画のみ生成(ファイル変更なし)+承認トークン |
W |
| 承認された計画を実行(デフォルトはコピー) |
W |
| ジャーナル記録だけを見て元に戻す |
推奨フロー
list_roots
→ scan_documents 어떤 문서가 있는지
→ outline_document 긴 문서는 뼈대부터
→ read_document 원문을 근거로 확보 (필요하면 이어 읽기)
→ (Claude가 요약 작성)
→ preview_save_summary 저장 내용 확인
→ [사용자 승인]
→ save_summary整理は別途行います。
preview_organize 계획만 생성 — 파일은 하나도 건드리지 않음
→ [사용자가 계획 확인·승인]
→ apply_organize (기본 copy)
→ 문제가 있으면 undo_last_organize整理基準は4つです。
基準 | 結果フォルダ |
|
|
|
|
|
|
| ルールで指定した名前。例: |
安全装置
パス封鎖 — すべての入力パスを
resolve()した後、許可ルート内か確認します。..、シンボリックリンク、ドライブ移動はすべてここでブロックされます。書き込み封鎖 — 保存は出力フォルダ内でのみ可能です。読み取りルートには書き込みません。
除外フォルダ —
.gitnode_modules.venvAppDataなどは走査も読み取りもしません。承認トークン — プレビュー内容のハッシュです。内容が1文字でも変わるとトークンが壊れ、保存・整理が拒否されます。ただし、トークンは技術的な整合性のみ保証し、ユーザーの承認に代わるものではありません。
デフォルトはコピー — 元のファイルの移動は
DOCS_MCP_ALLOW_MOVE=1がある場合のみ可能です。削除しない — 元に戻す場合もファイルを削除せず、
_trashフォルダに移動します。
検証
.venv/Scripts/python.exe -m pytest -q.venv/Scripts/python.exe scripts/smoke.py.venv/Scripts/python.exe scripts/simulate.pypytest— 形式別抽出・境界検査・承認フロー(単体)smoke.py— 実際のstdioでinitialize → tools/list → tools/callを確認simulate.py— 仮想ドキュメントセットを作成し、全体の流れを実際のMCP接続で再現します。議事録・契約書・見積書・プレゼン資料・PDF・CP949メモなどの仮想ドキュメント12個を作成し、走査→要約保存→整理→元に戻すまで進め、ブロックされるべきこと(ルート外の読み取り、トークン偽造、元のファイル移動)が実際にブロックされるかを確認します。一時フォルダで実行し、終わると自動で削除します。結果を残したい場合はフォルダを引数で渡してください。
制限
スキャン画像PDFにはテキストがありません。OCRは行わず、警告のみ残します。
Excelの日付セルは内部シリアル番号で表示される場合があります。
.hwp(バイナリ)は最善抽出です。表・脚注の順序が原文と異なる場合があります。画像内の文字はどの形式でも読み取りません。
ライセンス
MIT — LICENSE
Available Tools
11 toolsapply_organizeADestructive
승인된 정리 계획을 실제로 수행합니다. 기본은 복사이며, 이동은 서버 설정과 사용자 승인이 모두 있어야 합니다.
Inputs: target_dir (required), approval_token (required), mode, kinds, +5 more. Returns: mode, stage, status, journal, +5 more
build_summary_bundleARead-only
여러 문서를 글자 예산 안에서 고르게 발췌해 한 번에 돌려줍니다. 여러 문서를 묶어 요약할 때 씁니다.
Inputs: paths (required), char_budget. Returns: stage, status, included, documents, +6 more
list_rootsARead-only
이 서버가 읽을 수 있는 폴더, 저장 위치, 지원 형식과 한도를 확인합니다. 다른 도구를 부르기 전에 먼저 호출하세요.
Inputs: no named parameters. Returns: roots, stage, limits, status, +4 more
outline_documentARead-only
문서를 열어 구조(구역·제목·분량)와 키워드를 돌려줍니다. 전문을 읽기 전에 어디를 읽을지 고를 때 씁니다.
Inputs: path (required), keypoint_limit. Returns: kind, path, stage, status, +9 more
preview_organizeARead-only
문서를 어떤 폴더로 나눌지 계획만 만들어 보여줍니다. 파일을 전혀 건드리지 않습니다.
Inputs: target_dir (required), kinds, limit, folder, +3 more. Returns: plan, stage, total, status, +9 more
preview_save_summaryARead-only
요약문을 저장하기 전에 최종 파일 경로와 내용을 미리 보여주고 승인 토큰을 발급합니다. 파일을 쓰지 않습니다.
Inputs: title (required), sources (required), summary_markdown (required), note, +1 more. Returns: stage, status, reminder, target_path, +5 more
read_documentARead-only
문서 본문을 텍스트로 읽습니다. 구역 라벨([p.3], [슬라이드 2] 등)이 함께 붙어 요약에 근거를 달 수 있습니다.
Inputs: path (required), max_chars, start_char, only_labels. Returns: kind, path, text, stage, +8 more
save_summaryA
사용자가 승인한 요약을 출력 폴더에 저장합니다. preview_save_summary의 토큰이 필요합니다.
Inputs: title (required), sources (required), approval_token (required), summary_markdown (required), +2 more. Returns: path, bytes, stage, status, +2 more
scan_documentsARead-only
허용 폴더를 훑어 문서 목록을 최근 수정순으로 돌려줍니다. 파일 내용은 읽지 않습니다.
Inputs: kinds, limit, folder, name_pattern, +1 more. Returns: count, files, stage, stats, +3 more
search_documentsBRead-only
여러 문서의 본문을 실제로 열어 검색어를 찾고, 주변 문장을 근거 스니펫으로 돌려줍니다.
Inputs: query (required), kinds, folder, max_files. Returns: hits, count, query, stage, +4 more
undo_last_organizeADestructive
가장 최근(또는 지정한) 정리 실행을 되돌립니다. 복사본은 지우지 않고 _trash 폴더로 옮깁니다.
Inputs: journal_path. Returns: mode, stage, status, journal, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose: listing roots, scanning, outlining, reading, searching, bundling summaries, preview/save summaries, preview/apply organize, and undo. No two tools appear to overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_roots, scan_documents, preview_organize). Even compound verbs like preview_save_summary maintain the pattern.
11 tools is well-scoped for a local docs management server, covering read, search, summarize, save, and organize workflows without bloat. Each tool earns its place in the workflow.
The tool surface covers the full lifecycle for reading and managing documents: listing, scanning, outlining, reading, searching, bundling, saving summaries with preview, organizing with preview and apply, and undo for corrections. No obvious dead ends or missing operations for the stated purpose.
Related MCP Connectors
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Convert PDF pages into editable Word-ready text from your AI chat, all offline.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with local documents (PDF, Markdown, TXT) through tools for discovery, reading, extraction, summarization, comparison, keyword extraction, search, and analysis, ensuring privacy and offline capability.-
- FlicenseAqualityDmaintenanceEnables local analysis of unstructured documents (PDF, DOCX, PPTX, SVG, PNG) by extracting text and structure with citation anchors, and verifies summaries against source material before a human approves saving a report.9-
- FlicenseNot gradedqualityDmaintenanceEnables local folder analysis of unstructured documents (PDF, DOCX, PPTX, TXT, SVG, PNG, CSV, XLSX) by extracting structure, reading content, and generating reports, with a strict approval gate before any save operation.-
- FlicenseAqualityDmaintenanceEnables read-only scanning and text extraction from PDF, DOCX, PPTX, SVG, and PNG files in a local folder, providing the raw text to AI models for summarization or analysis without an external LLM API.5-