Skip to main content
Glama
local-docs-mcp

local-docs-mcp

local-docs-mcp

ローカルPCのドキュメントを読み、要約と整理を支援する個人用MCPサーバーです。 PDF・Word・Excel・PowerPoint・ハングル・Markdown・CSVなどをテキストに抽出し、要約の保存とファイル整理を承認手続きとともに処理します。

  • ネットワークは使いません。APIキーは不要です。

  • 要約はこのサーバーが行いません。 原文を正確に抽出すれば、要約はClaudeが書きます。(サーバーが提供するmachine_keypointsは頻度ベースの機械抽出であり、要約ではありません。)

  • 許可したフォルダの外は読み取れません。ファイルを移動・保存する際は必ず承認を経ます。

対応形式

種類

拡張子

方式

文書

.docx .docm

ZIP+XML直接パース(タイトル・段落・表)

ハングル

.hwpx / .hwp

hwpxは基本サポート、.hwpはolefileインストール時に最善抽出

PDF

.pdf

pypdf(ページごとにp.Nラベル)

プレゼン

.pptx .pptm

スライド番号順+発表者ノート

表

.xlsx .xlsm

シートごと、共有文字列の解釈

データ

.csv .tsv .json

列名・行数を含む

Web・メール

.html .htm .xml .eml

タグ除去、メールはヘッダー+本文

テキスト・コード

.md .txt .log .yaml .py .jsなど

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はマシンごとにパスが異なるため、リポジトリでは追跡しません。

環境変数

変数

意味

デフォルト値

DOCS_MCP_ROOTS

読み取りを許可するフォルダのリスト(;区切り)

デスクトップ・ドキュメント・ダウンロード

DOCS_MCP_OUTPUT

要約と整理記録を書き込むフォルダ

<HOME>/Desktop/docs-mcp-out

DOCS_MCP_MAX_FILE_MB

1ファイルの最大サイズ

20

DOCS_MCP_ALLOW_MOVE

1なら整理時に元のファイル移動を許可

未設定(コピーのみ)

ツール11個

読み取り専用(R)と書き込み(W)を区別して登録するため、ホストが承認UIを異なる形で表示します。

ツール

機能

R

list_roots

読み取り可能なフォルダ・対応形式・制限の確認

R

scan_documents

フォルダを走査してドキュメント一覧(種類・サイズ・更新日)

R

outline_document

構造・タイトル・キーワード・代表文。全文を読む前の判断用

R

read_document

本文抽出。セクションラベルと続き読みカーソルを提供

R

search_documents

複数ドキュメントの本文検索+根拠スニペット

R

build_summary_bundle

複数ドキュメントを文字予算内で均等に抜粋

R

preview_save_summary

保存する内容・パスのプレビュー+承認トークン発行

W

save_summary

承認された要約を出力フォルダに保存

R

preview_organize

整理計画のみ生成(ファイル変更なし)+承認トークン

W

apply_organize

承認された計画を実行(デフォルトはコピー)

W

undo_last_organize

ジャーナル記録だけを見て元に戻す

推奨フロー

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

整理は別途行います。

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

整理基準は4つです。

基準

結果フォルダ

by_kind

01_文書 02_PDF 03_プレゼン資料 04_表計算 …

by_month

202608のような更新月

by_kind_month

02_PDF/202608

by_keyword

ルールで指定した名前。例:{"契約書": ["契約","contract"]}

安全装置

  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

Available Tools

11 tools
apply_organizeA
Destructive

승인된 정리 계획을 실제로 수행합니다. 기본은 복사이며, 이동은 서버 설정과 사용자 승인이 모두 있어야 합니다.

Inputs: target_dir (required), approval_token (required), mode, kinds, +5 more. Returns: mode, stage, status, journal, +5 more

build_summary_bundleA
Read-only

여러 문서를 글자 예산 안에서 고르게 발췌해 한 번에 돌려줍니다. 여러 문서를 묶어 요약할 때 씁니다.

Inputs: paths (required), char_budget. Returns: stage, status, included, documents, +6 more

list_rootsA
Read-only

이 서버가 읽을 수 있는 폴더, 저장 위치, 지원 형식과 한도를 확인합니다. 다른 도구를 부르기 전에 먼저 호출하세요.

Inputs: no named parameters. Returns: roots, stage, limits, status, +4 more

outline_documentA
Read-only

문서를 열어 구조(구역·제목·분량)와 키워드를 돌려줍니다. 전문을 읽기 전에 어디를 읽을지 고를 때 씁니다.

Inputs: path (required), keypoint_limit. Returns: kind, path, stage, status, +9 more

preview_organizeA
Read-only

문서를 어떤 폴더로 나눌지 계획만 만들어 보여줍니다. 파일을 전혀 건드리지 않습니다.

Inputs: target_dir (required), kinds, limit, folder, +3 more. Returns: plan, stage, total, status, +9 more

preview_save_summaryA
Read-only

요약문을 저장하기 전에 최종 파일 경로와 내용을 미리 보여주고 승인 토큰을 발급합니다. 파일을 쓰지 않습니다.

Inputs: title (required), sources (required), summary_markdown (required), note, +1 more. Returns: stage, status, reminder, target_path, +5 more

read_documentA
Read-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_documentsA
Read-only

허용 폴더를 훑어 문서 목록을 최근 수정순으로 돌려줍니다. 파일 내용은 읽지 않습니다.

Inputs: kinds, limit, folder, name_pattern, +1 more. Returns: count, files, stage, stats, +3 more

search_documentsB
Read-only

여러 문서의 본문을 실제로 열어 검색어를 찾고, 주변 문장을 근거 스니펫으로 돌려줍니다.

Inputs: query (required), kinds, folder, max_files. Returns: hits, count, query, stage, +4 more

undo_last_organizeA
Destructive

가장 최근(또는 지정한) 정리 실행을 되돌립니다. 복사본은 지우지 않고 _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

    A4.1/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Enables 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
      -