convert_document
Convert Microsoft Office documents (Word, Excel, PowerPoint) to Markdown format with image extraction and optimization for Claude to read and process.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the Office document. Supported: .docx, .doc, .xlsx, .xls, .pptx, .ppt | |
| extract_images | No | Whether to extract and include images (default: true) | |
| image_format | No | How to handle images: 'file' saves to disk (recommended), 'base64' embeds in markdown, 'both' does both | file |
| output_name | No | Custom name for the output (without extension). If not provided, generates from filename. |
Implementation Reference
- src/officereader_mcp/server.py:177-221 (handler)The main handler for the 'convert_document' tool within the @server.call_tool() function. It validates input parameters, calls OfficeConverter.convert_file(), processes the result, and returns a JSON summary with paths and preview.
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]: """Handle tool calls.""" try: converter = get_converter() cache_notice = get_cache_location_notice(converter) if name == "convert_document": file_path = arguments.get("file_path") if not file_path: return [TextContent( type="text", text=json.dumps({"error": "file_path is required"}, ensure_ascii=False) )] extract_images = arguments.get("extract_images", True) image_format = arguments.get("image_format", "file") output_name = arguments.get("output_name") result = converter.convert_file( file_path=file_path, extract_images=extract_images, image_format=image_format, output_name=output_name, ) # Return summary with markdown preview response = { "status": "success", "file_type": result.get("file_type", "unknown"), "cache_location": str(converter.cache_dir), "output_path": result["output_path"], "conversion_dir": result["conversion_dir"], "images_extracted": len(result["images"]), "image_paths": result["images"], "metadata": result["metadata"], "markdown_preview": result["markdown"][:2000] + "..." if len(result["markdown"]) > 2000 else result["markdown"], "markdown_length": len(result["markdown"]), "hint": "Use 'list_conversions' to see all cached files, or 'read_converted_markdown' to read the full content.", } return [TextContent( type="text", text=f"{cache_notice}\n\n" + json.dumps(response, ensure_ascii=False, indent=2) )] - src/officereader_mcp/server.py:57-99 (schema)Input schema and description for the 'convert_document' tool, defining parameters like file_path, extract_images, image_format, and output_name.
Tool( name="convert_document", description=f"""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.""", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": f"Absolute path to the Office document. Supported: {supported_exts}", }, "extract_images": { "type": "boolean", "description": "Whether to extract and include images (default: true)", "default": True, }, "image_format": { "type": "string", "enum": ["file", "base64", "both"], "description": "How to handle images: 'file' saves to disk (recommended), 'base64' embeds in markdown, 'both' does both", "default": "file", }, "output_name": { "type": "string", "description": "Custom name for the output (without extension). If not provided, generates from filename.", }, }, "required": ["file_path"], }, ), - src/officereader_mcp/server.py:51-168 (registration)Registration of all tools including 'convert_document' via the @server.list_tools() decorator in the MCP server.
@server.list_tools() async def list_tools() -> list[Tool]: """List available tools for the MCP server.""" supported_exts = ", ".join(get_supported_extensions()) return [ Tool( name="convert_document", description=f"""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.""", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": f"Absolute path to the Office document. Supported: {supported_exts}", }, "extract_images": { "type": "boolean", "description": "Whether to extract and include images (default: true)", "default": True, }, "image_format": { "type": "string", "enum": ["file", "base64", "both"], "description": "How to handle images: 'file' saves to disk (recommended), 'base64' embeds in markdown, 'both' does both", "default": "file", }, "output_name": { "type": "string", "description": "Custom name for the output (without extension). If not provided, generates from filename.", }, }, "required": ["file_path"], }, ), Tool( name="read_converted_markdown", description="""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.""", inputSchema={ "type": "object", "properties": { "markdown_path": { "type": "string", "description": "Path to the markdown file (returned by convert_document)", }, }, "required": ["markdown_path"], }, ), Tool( name="list_conversions", description="""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.""", inputSchema={ "type": "object", "properties": {}, }, ), Tool( name="clear_cache", description="""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.""", inputSchema={ "type": "object", "properties": {}, }, ), Tool( name="get_document_metadata", description=f"""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: {supported_exts}""", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": f"Absolute path to the Office document. Supported: {supported_exts}", }, }, "required": ["file_path"], }, ), Tool( name="get_supported_formats", description="""Get list of all supported file formats. Returns a dictionary of file types (word, excel, powerpoint) and their extensions.""", inputSchema={ "type": "object", "properties": {}, }, ), ] - Core helper method OfficeConverter.convert_file() called by the handler. Detects document type and delegates to specialized converters (word, excel, powerpoint) for the actual conversion logic.
self, file_path: str, extract_images: bool = True, image_format: str = "file", output_name: Optional[str] = None, ) -> dict: """ Convert any supported Office document to Markdown. Args: file_path: Path to the document extract_images: Whether to extract images image_format: "file", "base64", or "both" output_name: Custom output name Returns: dict with markdown, images, metadata, and paths """ file_path = Path(file_path) if not file_path.exists(): raise FileNotFoundError(f"File not found: {file_path}") file_type = get_file_type(file_path) if file_type is None: supported = [] for exts in SUPPORTED_FORMATS.values(): supported.extend(exts) raise ValueError( f"Unsupported file format: {file_path.suffix}. " f"Supported formats: {', '.join(supported)}" ) # Generate output name if not output_name: file_hash = self._get_file_hash(file_path) output_name = f"{file_path.stem}_{file_hash[:8]}" # Create output directory conversion_dir = self.output_dir / output_name conversion_dir.mkdir(exist_ok=True) images_dir = conversion_dir / "images" images_dir.mkdir(exist_ok=True) # Convert based on file type if file_type == "word": result = self._docx_converter.convert_file( str(file_path), extract_images=extract_images, image_format=image_format, output_name=output_name, ) elif file_type == "excel": result = self.excel_converter.convert_file( str(file_path), extract_images=extract_images, image_format=image_format, output_name=output_name, conversion_dir=conversion_dir, images_dir=images_dir, ) elif file_type == "powerpoint": result = self.pptx_converter.convert_file( str(file_path), extract_images=extract_images, image_format=image_format, output_name=output_name, conversion_dir=conversion_dir, images_dir=images_dir, ) else: raise ValueError(f"Unknown file type: {file_type}") # Save markdown if not already saved (for Excel/PPT) md_path = conversion_dir / f"{output_name}.md" if "output_path" not in result: with open(md_path, "w", encoding="utf-8") as f: f.write(result["markdown"]) result["output_path"] = str(md_path) result["conversion_dir"] = str(conversion_dir) # Add file type info result["file_type"] = file_type return result