Office Reader MCP

OfficeReader MCP

一种模型上下文协议（MCP）服务器，通过智能图像提取和优化将Microsoft Office文档（Word、Excel、PowerPoint）转换为Markdown格式。

特性

• 多格式支持：Word（.docx、.doc）、Excel（.xlsx、.xls）、PowerPoint（.pptx、.ppt）
• 智能图像处理：使用WebP压缩进行自动提取和优化
• 格式保存：维护文档结构，包括标题、表格、列表和格式
• 元数据抽取：访问文档属性（作者、标题、创建日期等）
• 高效缓存：智能缓存系统，可快速重用转换后的文档
• 交叉平台的：适用于Windows、macOS和Linux

支持格式

安装

先决条件

• Python 3.10或更高版本
• 克劳德桌面或克劳德代码

步骤1：安装软件包

# Clone the repository
git clone https://github.com/Asunainlove/office-reader-mcp.git
cd office-reader-mcp

# Install in editable mode
pip install -e .

步骤2：配置Claude

适用于克劳德桌面

添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS/Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "officereader": {
      "command": "python",
      "args": ["-m", "officereader_mcp.server"],
      "env": {
        "OFFICEREADER_CACHE_DIR": "/path/to/cache"
      }
    }
  }
}

克劳德代码

添加到您的克劳德代码设置中：

视窗: %LOCALAPPDATA%\claude-code\settings.json macOS/Linux: ~/.config/claude-code/settings.json

{
  "mcpServers": {
    "officereader": {
      "command": "python",
      "args": ["-m", "officereader_mcp.server"],
      "env": {
        "OFFICEREADER_CACHE_DIR": "/path/to/cache"
      }
    }
  }
}

第三步：重启克劳德

重新启动Claude Desktop或Claude Code以加载MCP服务器。

快速开始

安装后，您可以在与Claude的对话中直接使用OfficeReader MCP：

Convert my Excel file at D:\Reports\sales_2024.xlsx to markdown

Extract text and images from D:\Presentations\keynote.pptx

Get metadata from my document at C:\Documents\report.docx

可用工具

1. convert_document

将任何支持的Office文档转换为Markdown格式。

参数：

• file_path （必填）：文档的绝对路径
• extract_images （可选，默认值：true）：提取嵌入图像
• image_format （可选，默认：“file”）：如何处理图像

- "file"：将图像保存到磁盘（推荐） - "base64"：在markdown中以base64格式嵌入图像 - "both"：保存和嵌入

• output_name （可选）：输出文件的自定义名称

例子：

Convert D:\Documents\report.xlsx with images

2. read_converted_markdown

读取之前转换的markdown文件的完整内容。

参数：

• markdown_path （必填）：markdown文件的路径

例子：

Read the markdown at D:\cache\output\report_abc12345\report_abc12345.md

3. list_conversions

列出所有缓存的文档转换及其详细信息。

例子：

List all converted documents

4. clear_cache

清除所有缓存的转换以释放磁盘空间。

例子：

Clear the document cache

5. get_document_metadata

从文档中提取元数据而不进行完全转换（更快）。

参数：

• file_path （必填）：文档路径

例子：

Get metadata from D:\Documents\presentation.pptx

6. get_supported_formats

获取所有支持的文件格式和扩展名的列表。

例子：

What file formats does officereader support?

输出结构

转换后的文档在缓存目录中组织：

cache/
└── output/
    └── document_name_abc12345/
        ├── document_name_abc12345.md    # Converted markdown
        └── images/
            ├── image_001.webp           # Optimized images
            ├── slide2_image_002.webp
            └── excel_image_003.webp

图像优化

图像会自动优化以减小文件大小，同时保持质量：

• 最大尺寸：1920×1080像素（可配置）
• 格式：WebP（首选）或PNG/JPEG回退
• 质量：80%用于照片，85%用于JPEG，无损PNG用于具有透明度的图形
• 典型压缩：尺寸减小50-80%
• 智能检测：自动区分照片和图形

技术细节

建筑

OfficeReader-MCP/
├── src/officereader_mcp/
│   ├── server.py              # MCP server implementation
│   ├── converter.py           # Word converter (DocxConverter, OfficeConverter)
│   ├── excel_converter.py    # Excel to Markdown converter
│   ├── pptx_converter.py     # PowerPoint to Markdown converter
│   ├── image_optimizer.py    # Image compression utility
│   └── __init__.py           # Package initialization
├── test/
│   ├── test_converter.py     # Basic functionality tests
│   └── test_all_formats.py   # Comprehensive test suite
├── pyproject.toml            # Project configuration
└── README.md                 # Documentation

依赖项

运行时，所有依赖项都会自动安装 pip install -e .

测试

运行测试

# Basic converter test
python test/test_converter.py

# Comprehensive test suite for all formats
python test/test_all_formats.py

# Test with a specific document
python test/test_converter.py path/to/your/document.docx

测试覆盖率

测试套件验证：

• 模块导入和初始化
• 所有格式的转换器功能
• 图像提取和优化
• 文件类型检测
• 缓存管理
• 元数据抽取

配置

OfficeReader MCP支持多种配置方法来自定义缓存位置和行为。

快速配置（推荐）

1. 复制示例配置文件：

   cp config.example.json config.json

1. 编辑 config.json 要设置缓存目录，请执行以下操作：

   {
     "cache_dir": "D:/MyDocuments/OfficeReaderCache",
     "image_optimization": {
       "enabled": true,
       "max_dimension": 1920,
       "quality": 80
     }
   }

1. 配置文件将在启动时自动加载。

有关详细的配置选项，请参阅 CONFIG.md.

环境变量

示例用法：

# Set custom cache directory
export OFFICEREADER_CACHE_DIR=/path/to/custom/cache

# Or in Windows
set OFFICEREADER_CACHE_DIR=C:\path\to\custom\cache

备注：环境变量优先于配置文件设置。

使用示例

使用多个工作表转换Excel

User: Convert my Excel file at D:\Reports\Q4_sales.xlsx

Claude: I'll convert that Excel file. Each sheet will be converted to a separate
        section in the markdown with properly formatted tables...

[Output includes all sheets as markdown tables with preserved formatting]

提取PowerPoint内容

User: Extract all text and images from D:\Presentations\product_launch.pptx

Claude: Converting the PowerPoint presentation. I'll extract text from each slide,
        including speaker notes, along with all embedded images...

[Output includes slide-by-slide breakdown with images and notes]

批处理

User: Convert all Office documents in D:\Documents\

Claude: I'll convert each document and cache the results for quick access...

[Processes all supported files and provides summary]

故障排除

“找不到模块”错误

# Reinstall the package
pip install -e .

配置未加载

1. 验证配置文件位置是否正确
2. 检查JSON语法是否有效（使用JSON验证器）
3. 完全重新启动克劳德桌面或克劳德代码
4. 检查日志中的错误消息

未提取的图像

可能的原因：

• 文档包含链接的图像（未嵌入）
• 缓存目录的写入权限不足
• 文档库不支持图像格式

解决方案：

# Verify cache directory is writable
ls -la /path/to/cache  # Unix/Mac
dir /path/to/cache     # Windows

# Check if images are embedded
# Use convert_document with extract_images=true explicitly

编码问题

转换器始终使用UTF-8编码。如果您看到乱码文本：

• 检查源文档编码
• 确保您的终端/控制台支持UTF-8
• 尝试使用不同的系统区域设置进行转换

更新日志

v2.0.0（2024-11）

主要特点：

• 添加了Excel（.xlsx、.xls）支持，支持多页转换
• 添加了PowerPoint（.pptx、.ppt）支持和幻灯片提取功能
• 利用WebP压缩实现智能图像优化
• 为所有文档类型添加了统一的OfficeConverter接口
• 增强所有格式的元数据提取

改进：

• 基于哈希的文件识别智能缓存系统
• 延迟加载特定格式的转换器以获得更好的性能
• 更好的错误处理和验证
• 适用于所有格式的全面测试套件

工具：

• 添加 get_supported_formats 工具
• 增强 get_document_metadata 适用于所有格式
• 改进的 list_conversions 具有详细的缓存信息

v1.0.0（2024-09）

• 初始版本
• Word文档（.docx、.doc）转换
• 基本图像提取
• MCP服务器实现

贡献

欢迎投稿！以下是您可以提供帮助的方式：

1. 报告Bug：打开一个包含详细信息和复制步骤的问题
2. 建议功能：描述你的想法和用例
3. 提交拉取请求:

- 复刻仓库 - 创建要素分支(git checkout -b feature/amazing-feature) - 提交您的更改(git commit -m 'Add amazing feature') - 推到您的分支(git push origin feature/amazing-feature) - 打开拉取请求

开发设置

# Clone and install with dev dependencies
git clone https://github.com/Asunainlove/office-reader-mcp.git
cd office-reader-mcp
pip install -e ".[dev]"

# Run tests
python test/test_all_formats.py

# Run linting (if configured)
black src/
ruff check src/

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

作者

Asunainlove

• github： @Asunainlove
• 存储库： 办公室阅读器mcp
• 问题： 报告错误

致谢

本项目使用以下开源库：

• 模型上下文协议（MCP） 通过Anthropic
• python docx 用于文字处理
• openpyxl 用于Excel处理
• python pptx 用于PowerPoint处理
• 枕头 用于图像处理

支持

如果你觉得这个项目有帮助，请：

• ⭐ 为存储库添加星号
• 🐛 报告错误和问题
• 💡 建议新功能
• 🔀 贡献代码改进

______________________________________________________________________

转换愉快！ 🚀