OfficeReader-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OfficeReader-MCP convert my presentation at /home/user/slides.pptx to markdown with images"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OfficeReader-MCP
A Model Context Protocol (MCP) server that converts Microsoft Office documents (Word, Excel, PowerPoint) to Markdown format with intelligent image extraction and optimization.
Features
Multi-Format Support: Word (.docx, .doc), Excel (.xlsx, .xls), PowerPoint (.pptx, .ppt)
Intelligent Image Processing: Automatic extraction and optimization with WebP compression
Format Preservation: Maintains document structure including headings, tables, lists, and formatting
Metadata Extraction: Access document properties (author, title, creation date, etc.)
Efficient Caching: Smart caching system for quick reuse of converted documents
Cross-Platform: Works on Windows, macOS, and Linux
Related MCP server: MCP Document Converter
Supported Formats
Format | Extensions | Features |
Word |
| Text formatting, headings, lists, tables, images |
Excel |
| Multi-sheet support, tables, charts, embedded images |
PowerPoint |
| Slides, text boxes, images, speaker notes, tables |
Installation
Prerequisites
Python 3.10 or higher
Claude Desktop or Claude Code
Step 1: Install the Package
# Clone the repository
git clone https://github.com/Asunainlove/office-reader-mcp.git
cd office-reader-mcp
# Install in editable mode
pip install -e .Step 2: Configure Claude
For Claude Desktop
Add to your Claude Desktop config file:
Windows: %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"
}
}
}
}For Claude Code
Add to your Claude Code settings:
Windows: %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"
}
}
}
}Step 3: Restart Claude
Restart Claude Desktop or Claude Code to load the MCP server.
Quick Start
After installation, you can use OfficeReader-MCP directly in your conversations with Claude:
Convert my Excel file at D:\Reports\sales_2024.xlsx to markdownExtract text and images from D:\Presentations\keynote.pptxGet metadata from my document at C:\Documents\report.docxAvailable Tools
1. convert_document
Convert any supported Office document to Markdown format.
Parameters:
file_path(required): Absolute path to the documentextract_images(optional, default: true): Extract embedded imagesimage_format(optional, default: "file"): How to handle images"file": Save images to disk (recommended)"base64": Embed images as base64 in markdown"both": Both save and embed
output_name(optional): Custom name for output files
Example:
Convert D:\Documents\report.xlsx with images2. read_converted_markdown
Read the full content of a previously converted markdown file.
Parameters:
markdown_path(required): Path to the markdown file
Example:
Read the markdown at D:\cache\output\report_abc12345\report_abc12345.md3. list_conversions
List all cached document conversions with details.
Example:
List all converted documents4. clear_cache
Clear all cached conversions to free up disk space.
Example:
Clear the document cache5. get_document_metadata
Extract metadata from a document without full conversion (faster).
Parameters:
file_path(required): Path to the document
Example:
Get metadata from D:\Documents\presentation.pptx6. get_supported_formats
Get list of all supported file formats and extensions.
Example:
What file formats does officereader support?Output Structure
Converted documents are organized in the cache directory:
cache/
āāā output/
āāā document_name_abc12345/
āāā document_name_abc12345.md # Converted markdown
āāā images/
āāā image_001.webp # Optimized images
āāā slide2_image_002.webp
āāā excel_image_003.webpImage Optimization
Images are automatically optimized to reduce file size while maintaining quality:
Max Dimensions: 1920Ć1080 pixels (configurable)
Format: WebP (preferred) or PNG/JPEG fallback
Quality: 80% for photos, 85% for JPEG, lossless PNG for graphics with transparency
Typical Compression: 50-80% size reduction
Smart Detection: Automatically distinguishes between photos and graphics
Technical Details
Architecture
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 # DocumentationDependencies
Package | Version | Purpose |
| >=1.0.0 | Model Context Protocol SDK |
| >=1.1.0 | DOCX file parsing and manipulation |
| >=1.6.0 | DOC/DOCX to HTML conversion (fallback) |
| >=10.0.0 | Image processing and optimization |
| >=0.11.0 | HTML to Markdown conversion |
| >=3.1.0 | Excel file parsing |
| >=0.6.21 | PowerPoint file parsing |
All dependencies are automatically installed when you run pip install -e .
Testing
Run Tests
# 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.docxTest Coverage
The test suite verifies:
Module imports and initialization
Converter functionality for all formats
Image extraction and optimization
File type detection
Cache management
Metadata extraction
Configuration
OfficeReader-MCP supports multiple configuration methods to customize cache locations and behavior.
Quick Configuration (Recommended)
Copy the example config file:
cp config.example.json config.jsonEdit
config.jsonto set your cache directory:{ "cache_dir": "D:/MyDocuments/OfficeReaderCache", "image_optimization": { "enabled": true, "max_dimension": 1920, "quality": 80 } }The config file will be automatically loaded on startup.
For detailed configuration options, see CONFIG.md.
Environment Variables
Variable | Description | Default |
| Directory for cached conversions | System temp directory |
Example usage:
# Set custom cache directory
export OFFICEREADER_CACHE_DIR=/path/to/custom/cache
# Or in Windows
set OFFICEREADER_CACHE_DIR=C:\path\to\custom\cacheNote: Environment variables take priority over config file settings.
Usage Examples
Converting Excel with Multiple Sheets
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]Extracting PowerPoint Content
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]Batch Processing
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]Troubleshooting
"Module not found" Error
# Reinstall the package
pip install -e .Configuration Not Loading
Verify the config file location is correct
Check JSON syntax is valid (use a JSON validator)
Restart Claude Desktop or Claude Code completely
Check logs for error messages
Images Not Extracting
Possible causes:
Document contains linked images (not embedded)
Insufficient write permissions for cache directory
Image format not supported by the document library
Solution:
# 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 explicitlyEncoding Issues
The converter uses UTF-8 encoding throughout. If you see garbled text:
Check the source document encoding
Ensure your terminal/console supports UTF-8
Try converting with different system locale settings
Changelog
v2.0.0 (2024-11)
Major Features:
Added Excel (.xlsx, .xls) support with multi-sheet conversion
Added PowerPoint (.pptx, .ppt) support with slide extraction
Implemented intelligent image optimization with WebP compression
Added unified OfficeConverter interface for all document types
Enhanced metadata extraction for all formats
Improvements:
Smart caching system with hash-based file identification
Lazy-loading of format-specific converters for better performance
Better error handling and validation
Comprehensive test suite for all formats
Tools:
Added
get_supported_formatstoolEnhanced
get_document_metadatafor all formatsImproved
list_conversionswith detailed cache information
v1.0.0 (2024-09)
Initial release
Word document (.docx, .doc) conversion
Basic image extraction
MCP server implementation
Contributing
Contributions are welcome! Here's how you can help:
Report Bugs: Open an issue with details and steps to reproduce
Suggest Features: Describe your idea and use case
Submit Pull Requests:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to your branch (
git push origin feature/amazing-feature)Open a Pull Request
Development Setup
# 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/License
MIT License - see LICENSE file for details.
Author
Asunainlove
GitHub: @Asunainlove
Repository: office-reader-mcp
Issues: Report a bug
Acknowledgments
This project uses the following open-source libraries:
Model Context Protocol (MCP) by Anthropic
python-docx for Word processing
openpyxl for Excel processing
python-pptx for PowerPoint processing
Pillow for image processing
Support
If you find this project helpful, please:
ā Star the repository
š Report bugs and issues
š” Suggest new features
š Contribute code improvements
Happy converting! š
Available Tools
6 toolsclear_cacheA
Clear all cached conversions.
Removes all converted markdown files and extracted images from the cache. Use this to free up disk space or reset the conversion cache.
Inputs: no named parameters.
convert_documentA
Convert Office documents to Markdown format for Claude to read.
Supported formats:
Word: .docx, .doc
Excel: .xlsx, .xls (converts each sheet to a Markdown table)
PowerPoint: .pptx, .ppt (extracts text and images from slides)
Features:
Text extraction with formatting (headings, bold, italic, lists, tables)
Image extraction and optimization (auto-compressed for efficiency)
Speaker notes extraction from PowerPoint
Multi-sheet support for Excel
Images are automatically optimized (WebP format, max 1920x1080) to reduce size while maintaining readability for Claude.
Inputs: file_path (required), extract_images, image_format, output_name.
get_document_metadataA
Get metadata from an Office document without full conversion.
Extracts document properties like title, author, creation date, etc. Faster than full conversion when you only need metadata.
Supported formats: .docx, .doc, .xlsx, .xls, .pptx, .ppt
Inputs: file_path (required).
get_supported_formatsB
Get list of all supported file formats.
Returns a dictionary of file types (word, excel, powerpoint) and their extensions.
Inputs: no named parameters.
list_conversionsB
List all cached document conversions.
Shows all documents that have been converted, including their output paths and number of extracted images. Useful for finding previously converted files.
Inputs: no named parameters.
read_converted_markdownA
Read the content of a previously converted markdown file.
Use this after convert_document to get the actual markdown content. This is useful when you want to process or analyze the converted document.
Inputs: markdown_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose with no overlap: clear_cache manages cache, convert_document performs conversions, get_document_metadata extracts metadata, get_supported_formats lists formats, list_conversions shows cached items, and read_converted_markdown reads converted content. The descriptions reinforce these distinct roles, making misselection unlikely.
All tool names follow a consistent verb_noun pattern (e.g., clear_cache, convert_document, get_document_metadata, get_supported_formats, list_conversions, read_converted_markdown). This uniformity in naming makes the tool set predictable and easy to navigate for an agent.
With 6 tools, the count is well-scoped for the server's purpose of reading Office documents. Each tool serves a specific function in the conversion and caching workflow, from format support to content retrieval, without being excessive or insufficient for the domain.
The tool set provides complete coverage for the Office document reading domain: it supports conversion (convert_document), metadata retrieval (get_document_metadata), format listing (get_supported_formats), cache management (clear_cache, list_conversions), and content access (read_converted_markdown). There are no obvious gaps in the lifecycle from input to output.
Maintenance
Related MCP Connectors
Document to Markdown: convert Word, Excel, PowerPoint and PDF files to Markdown for an LLM.
Convert Word, Excel, PowerPoint, OpenDocument, EPUB and RTF files to Markdown for LLMs and RAG
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
PDF, Word, PowerPoint and Excel to clean Markdown plus every table as JSON rows, OCR for scans.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConverts various file types (documents, images, audio, web content) to markdown format without requiring Docker, supporting PDF, Word, Excel, PowerPoint, images, audio files, web URLs, and more.397 npm14MIT
- AlicenseNot gradedqualityDmaintenanceConverts DOCX files to Markdown with formatting preservation and image extraction, and provides image analysis tools for document processing workflows.5 npmMIT
- AlicenseAqualityDmaintenanceConverts various file types (PDF, images, audio, DOCX, XLSX, PPTX) and web content (YouTube videos, web pages, Bing search results) into Markdown format for easy reading and sharing.10MIT
- FlicenseNot gradedqualityDmaintenanceConverts images, PDFs, Word documents, and Excel spreadsheets to structured markdown using Nanonets OCR, with support for tables, LaTeX equations, and complex layouts.1-