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.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    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
      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
      -