MCP Document Reader

Características

• Lectura y escritura integradas: Puede leer documentos y generar archivos de Word / PowerPoint basados en parámetros estructurados.

• Amplio soporte de formatos: Compatible con TXT, CSV, Markdown, DOC, DOCX, PDF, PPT, PPTX, EPUB, XLSX, XLS.

• Escritura estructurada: Admite la generación de párrafos, tablas, páginas de título, páginas de puntos clave y tablas de presentación.

• Exportación a formatos antiguos: Permite exportar a .doc y .ppt si LibreOffice está instalado.

• Protocolo MCP: Cumple con el estándar MCP y puede utilizarse como herramienta para asistentes de IA (como Trae IDE).

• Fácil integración: Configuración sencilla para un uso inmediato.

• Rendimiento fiable: Pruebas automatizadas que cubren lectura, generación, retroceso de conversión e interfaces de herramientas.

• Soporte del sistema de archivos: Lectura y escritura de documentos directamente desde el sistema de archivos.

📚 Centro de documentación

Guía del usuario · Referencia de API · Guía de contribución · Registro de cambios · Licencia

Arquitectura

graph TB
    A[AI Assistant / User<br/>AI 助手 / 用户] -->|Call MCP tools<br/>调用 MCP 工具| B[MCP Document Reader<br/>MCP 文档读取器]
    B -->|Read<br/>读取| C[Document Readers<br/>文档读取器]
    B -->|Generate<br/>生成| D[Document Writers<br/>文档生成器]
    C -->|TXT / CSV / MD| E[Text-based Readers<br/>文本类读取器]
    C -->|DOC / DOCX| F[Word Readers<br/>Word 读取器]
    C -->|PPT / PPTX| G[Presentation Readers<br/>演示读取器]
    C -->|PDF / EPUB / Excel| H[Structured Readers<br/>结构化读取器]
    D -->|write_word_document| I[DOCX Builder<br/>DOCX 生成器]
    D -->|write_presentation| J[PPTX Builder<br/>PPTX 生成器]
    I -->|Optional conversion<br/>可选转换| K[LibreOffice -> DOC]
    J -->|Optional conversion<br/>可选转换| L[LibreOffice -> PPT]
    E --> M[Return text / metadata<br/>返回文本 / 元数据]
    F --> M
    G --> M
    H --> M
    K --> M
    L --> M
    M --> A
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#f0f0f0
    style D fill:#e8f5e9
    style E fill:#e8f5e9
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style H fill:#fff9c4

Formatos admitidos

Instalación

Usando pip (recomendado)

pip install mcp-documents-reader

Si necesita la función de generación de PowerPoint, asegúrese de que python-pptx esté disponible en el entorno de ejecución.

Si necesita exportar a formatos antiguos .doc o .ppt, instale LibreOffice y asegúrese de que soffice o libreoffice se hayan añadido al PATH.

Instalación desde el código fuente

git clone https://github.com/xt765/mcp_documents_reader.git
cd mcp_documents_reader
pip install -e .

Herramientas MCP

Este servidor proporciona las siguientes herramientas:

read_document

Utiliza una interfaz unificada para leer cualquier tipo de documento admitido.

Parámetros:

• filename (string, obligatorio): Ruta del archivo del documento, admite rutas absolutas o relativas.

extract_document_images

Extrae imágenes incrustadas en archivos DOCX y devuelve metadatos JSON estructurados.

Parámetros:

• filename (string, obligatorio): Ruta del archivo DOCX.

• output_dir (string, opcional): Directorio para exportar las imágenes.

write_word_document

Genera un documento de Word .docx o exporta a .doc mediante la conversión de LibreOffice.

Parámetros:

• filename (string, obligatorio): Ruta de salida, la extensión debe ser .docx o .doc.

• title (string, opcional): Título del documento.

• paragraphs (matriz de strings, opcional): Párrafos escritos en orden.

• tables (matriz de objetos, opcional): Definición de tablas, admite title, headers, rows.

write_presentation

Genera una presentación .pptx o exporta a .ppt mediante la conversión de LibreOffice.

Parámetros:

• filename (string, obligatorio): Ruta de salida, la extensión debe ser .pptx o .ppt.

• title (string, opcional): Título de la página de título.

• subtitle (string, opcional): Subtítulo de la página de título.

• slides (matriz de objetos, opcional): Definición de diapositivas, admite title, paragraphs, bullets, table.

Configuración

Uso en Trae IDE / Claude Desktop

Añada el siguiente contenido a su archivo de configuración MCP:

Opción 1: Usando PyPI (recomendado)

{
  "mcpServers": {
    "mcp-document-reader": {
      "command": "uvx",
      "args": [
        "mcp-documents-reader"
      ]
    }
  }
}

Opción 2: Usando el repositorio de GitHub

{
  "mcpServers": {
    "mcp-document-reader": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/xt765/mcp_documents_reader",
        "mcp_documents_reader"
      ]
    }
  }
}

Opción 3: Usando el repositorio de Gitee (acceso más rápido en China)

{
  "mcpServers": {
    "mcp-document-reader": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://gitee.com/xt765/mcp_documents_reader",
        "mcp_documents_reader"
      ]
    }
  }
}

Modo de uso

Como herramienta MCP

Una vez configurado, el asistente de IA puede invocar directamente las siguientes herramientas:

# 读取 DOCX 文件
read_document(filename="example.docx")

# 读取演示文稿
read_document(filename="example.pptx")

# 生成 DOCX 报告
write_word_document(
    filename="report.docx",
    title="周报",
    paragraphs=["本周总结", "下周计划"],
    tables=[
        {
            "title": "指标表",
            "headers": ["名称", "数值"],
            "rows": [["线索", 42], ["成交", 8]],
        }
    ],
)

# 生成 PPTX 汇报
write_presentation(
    filename="briefing.pptx",
    title="季度汇报",
    subtitle="Q2",
    slides=[
        {
            "title": "亮点",
            "paragraphs": ["概述段落"],
            "bullets": ["重点 A", "重点 B"],
        }
    ],
)

Como biblioteca de Python

from mcp_documents_reader import DocumentReaderFactory

# 使用工厂类（推荐）
reader = DocumentReaderFactory.get_reader("document.pdf")
content = reader.read("/path/to/document.pdf")

# 检查格式是否支持
if DocumentReaderFactory.is_supported("file.xlsx"):
    reader = DocumentReaderFactory.get_reader("file.xlsx")
    content = reader.read("/path/to/file.xlsx")

Detalles de la interfaz de herramientas

read_document

Lee cualquier tipo de documento admitido.

extract_document_images

Extrae imágenes incrustadas en archivos DOCX.

write_word_document

Genera DOCX directamente o exporta DOC mediante conversión de LibreOffice.

write_presentation

Genera PPTX directamente o exporta PPT mediante conversión de LibreOffice.

Dependencias

Dependencias principales

• mcp >= 1.26.0 - Implementación del protocolo MCP

• python-docx >= 1.2.0 - Lectura de DOCX y generación de documentos Word

• python-pptx >= 0.6.23 - Generación de documentos PowerPoint

• pypdf >= 6.8.0 - Lectura de archivos PDF (reemplaza a PyPDF2)

• openpyxl >= 3.1.5 - Lectura de archivos Excel

Dependencias de tiempo de ejecución opcionales

• LibreOffice - Obligatorio si desea exportar a formatos antiguos .doc o .ppt

• antiword / catppt - Comandos auxiliares opcionales para la lectura de formatos antiguos .doc / .ppt

Dependencias de desarrollo

• pytest >= 8.0.0 - Marco de pruebas

• pytest-asyncio >= 0.24.0 - Soporte para pruebas asíncronas

• pytest-cov >= 6.0.0 - Informes de cobertura

• basedpyright >= 0.28.0 - Comprobación de tipos

• ruff >= 0.8.0 - Linting y formateo de código

Licencia

Este proyecto es de código abierto bajo la Licencia MIT.

Este proyecto es un desarrollo derivado basado en el excelente proyecto de código abierto xt765/mcp_documents_reader, sobre el cual se han realizado mejoras adicionales.

Actualmente hemos añadido y mejorado principalmente las siguientes capacidades:

• Capacidad de extracción de imágenes dentro de documentos

• Flujos de trabajo de escritura y generación de documentos de Word y PowerPoint

• Soporte de creación de documentos más completo orientado a escenarios MCP

Muchas gracias al autor del repositorio original por proporcionar las capacidades básicas y el trabajo de código abierto.

Contribución

¡Las propuestas (Issues) y solicitudes de extracción (Pull Requests) son bienvenidas!

Proyectos relacionados

• MCP Document Converter - Convertidor de documentos MCP, admite conversión entre múltiples formatos

• Model Context Protocol - Documentación oficial del Protocolo de contexto de modelo