local-docs-mcp

Servidor MCP personal que lee documentos del PC local para ayudar con el resumen y la organización. Extrae texto de PDF, Word, Excel, PowerPoint, HWP (한글), Markdown, CSV, etc., y gestiona el guardado de resúmenes y la organización de archivos con un proceso de aprobación.

• No usa red. No necesita claves de API.

• El resumen no lo hace este servidor. Si extrae el texto original con precisión, el resumen lo escribe Claude. (Los machine_keypoints que entrega el servidor son una extracción mecánica basada en frecuencia, no un resumen).

• No puede leer fuera de las carpetas permitidas. Para mover o guardar archivos siempre se requiere aprobación.

Formatos admitidos

.doc .xls .ppt (antiguos formatos binarios) no se leen y se indica que "guarde en un formato con x".

Related MCP server: Knowledge Assistant MCP

Instalación

Se requiere Python 3.11 o superior.

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

En macOS y Linux se usa .venv/bin/pip. [formats] instala pypdf para PDF y olefile para .hwp (binario); si no están, el resto de formatos sigue funcionando.

Registro en Claude Code

<PROJECT_DIR> es la ruta absoluta donde clonó este repositorio, y <HOME> es la carpeta de usuario.

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

Si solo quiere usarlo dentro de este repositorio, copie .mcp.json.example como .mcp.json y sustituya <PROJECT_DIR> y <HOME> por las rutas reales. .mcp.json no se rastrea en el repositorio porque las rutas varían según la máquina.

Variables de entorno

11 herramientas

Se registran distinguiendo solo lectura (R) y escritura (W), de modo que el host muestra una interfaz de aprobación distinta para cada caso.

Flujo recomendado

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

La organización se realiza por separado.

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

Hay cuatro criterios de organización.

Medidas de seguridad

1. Bloqueo de rutas — todas las rutas de entrada se comprueban con resolve() para verificar que están dentro de las raíces permitidas. .., enlaces simbólicos y cambios de unidad quedan bloqueados aquí.

2. Bloqueo de escritura — el guardado solo es posible dentro de la carpeta de salida. No se escribe en las raíces de lectura.

3. Carpetas excluidas — .git, node_modules, .venv, AppData, etc. no se recorren ni se leen.

4. Token de aprobación — es el hash del contenido de la vista previa. Si el contenido cambia aunque sea un solo carácter, el token se invalida y se rechaza el guardado o la organización. No obstante, el token solo garantiza la integridad técnica y no sustituye la aprobación del usuario.

5. Por defecto se copia — mover el original solo es posible con DOCS_MCP_ALLOW_MOVE=1.

6. No se elimina nada — la reversión tampoco borra archivos; los mueve a la carpeta _trash.

Verificación

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

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

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

• pytest — extracción por formato, pruebas de límites y flujo de aprobación (unitarias)

• smoke.py — comprueba initialize → tools/list → tools/call con stdio real

• simulate.py — crea un conjunto de documentos ficticios y reproduce el flujo completo con una conexión MCP real. Crea 12 documentos ficticios (actas de reunión, contratos, presupuestos, presentaciones, PDF, notas CP949, etc.) y recorre exploración → guardado de resumen → organización → reversión, verificando que lo que debe bloquearse (lectura fuera de las raíces, token falsificado, movimiento de originales) realmente se bloquea. Se ejecuta en una carpeta temporal y se elimina solo al terminar. Si quiere conservar los resultados, pase una carpeta como argumento.

Limitaciones

• Los PDF escaneados como imagen no tienen texto. No se hace OCR; solo se deja una advertencia.

• Las celdas de fecha de Excel pueden mostrarse como número de serie interno.

• .hwp (binario) es una extracción aproximada. El orden de tablas y notas al pie puede diferir del original.

• El texto dentro de imágenes no se lee en ningún formato.

Licencia

MIT — LICENSE