Huoshui File Converter
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., "@Huoshui File Converter convert notes.md to PDF"
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.
Huoshui File Converter
A secure MCP (Model Context Protocol) server for document format conversion within a specified working directory.
Features
๐ Sandbox Security: All operations restricted to a configured working directory
๐ Format Support: Convert between Markdown, DOCX, HTML, PDF, and TXT
๐ MCP Integration: Full MCP protocol support with prompts, resources, and tools
โ๏ธ Flexible Configuration: CLI arguments, environment variables, or current directory
๐ Smart Detection: Intelligent file format detection by content analysis
Related MCP server: doc-ops-mcp
Quick Start
Installation
Option 1: From MCP Registry (Recommended)
This server is available in the Model Context Protocol Registry. Install it using your MCP client.
mcp-name: io.github.huoshuiai42/huoshui-file-converter
Option 2: Using uvx
uvx huoshui-file-converterOption 3: Using pip
pip install huoshui-file-converterBasic Usage
# Use current directory
uvx huoshui-file-converter
# Specify working directory (recommended)
uvx huoshui-file-converter --dir "/path/to/documents"
# Short form
uvx huoshui-file-converter -d "~/Documents"MCP Client Configuration
For Claude Desktop or other MCP clients:
{
"mcpServers": {
"huoshui-converter": {
"command": "uvx",
"args": ["huoshui-file-converter", "--dir", "/Users/yourname/Documents"]
}
}
}Configuration Options
Priority Order
CLI Argument (highest priority):
--diror-dEnvironment Variable:
HUOSHUI_WORKING_DIRSmart Default: Documents folder if current directory is problematic
Current Directory (fallback)
Examples
# CLI argument (best for MCP clients)
uvx huoshui-file-converter --dir "/project/docs"
# Environment variable
export HUOSHUI_WORKING_DIR="/project/docs"
uvx huoshui-file-converter
# Current directory fallback
cd /project/docs
uvx huoshui-file-converterSupported Conversions
From | To |
Markdown | DOCX, HTML, PDF |
DOCX | Markdown, HTML, PDF |
HTML | Markdown, DOCX, PDF |
TXT | Markdown, DOCX, HTML, PDF |
MCP Tools & Resources
Tools
convert_document: Convert files between formatsdetect_format: Intelligent format detection
Resources
file_list: Browse directory contents (optimized for large directories)limit: Control number of files shown (default: 100)supported_only: Show only convertible files
file_get: Get detailed file informationconversion_capability_list: List supported conversions
Prompts
role_and_rules: AI assistant behavior guidelines
Performance Features
Fast Directory Listing: Extension-based format detection for large directories
Smart File Limits: Default 100-file limit prevents UI freezing
Large File Handling: Files >50MB are marked and handled specially
Selective Display: Option to show only supported file formats
Memory Efficient: Avoids reading file contents during directory browsing
Security Features
Path Validation: Prevents directory traversal attacks
Working Directory Restriction: All operations sandboxed to configured directory
Startup Validation: Checks directory existence and permissions
Relative Path Enforcement: Absolute paths are rejected
Command Line Options
$ uvx huoshui-file-converter --help
usage: huoshui-file-converter [-h] [--dir PATH] [--version]
Huoshui Document Converter - MCP Server for file conversion within a working directory
options:
-h, --help show this help message and exit
--dir PATH, -d PATH
Working directory for file operations (default: current directory or HUOSHUI_WORKING_DIR env var)
--version, -v show program's version number and exit
Examples:
uvx huoshui-file-converter # Use current directory
uvx huoshui-file-converter --dir /docs # Use specific directory
uvx huoshui-file-converter -d ./project # Use relative directory
Configuration Priority:
1. CLI argument (--dir/-d)
2. Environment variable (HUOSHUI_WORKING_DIR)
3. Current working directoryError Handling
The server validates the working directory on startup:
โ
Working directory configured: /Users/name/Documents
๐ Source: CLI argumentCommon errors and solutions:
Error | Solution |
Directory not found | Create directory or fix path |
No write access | Check permissions ( |
Path outside sandbox | Use relative paths only |
Development
Requirements
Python 3.8+
pypandoc
pandoc (system dependency)
LaTeX (for PDF conversion)
Testing
# Test configuration
uvx huoshui-file-converter --dir "/tmp/test"
# Check startup messages
# โ
Working directory configured: /tmp/test
# ๐ Source: CLI argumentDocumentation
License
[Your license here]
Available Tools
3 toolsconvert_documentA
Converts a specified file to a different format. The new file is saved in the same directory as the original.
Args: file_path: File path (absolute or relative to home directory) to_format: The target format to convert the file into
Returns: Dictionary with new_file_path key containing the absolute path of converted file
Inputs: file_path (required), to_format (required).
detect_formatA
Intelligently detects a file's true format by inspecting its contents, which is more reliable than trusting a file extension.
Args: file_path: File path (absolute or relative to home directory)
Returns: Dictionary with format key containing the detected file format
Inputs: file_path (required).
file_getB
Retrieves detailed information about a single file.
Args: path: File path (absolute or relative to home directory)
Returns: File resource with detailed information
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: file conversion, format detection, and file info retrieval. No overlap or ambiguity.
All tool names follow a consistent verb_noun snake_case pattern: convert_document, detect_format, file_get.
With 3 tools, the surface is well-scoped for a file conversion utility. Each tool earns its place without being overly sparse.
Covers core conversion workflow (detect + convert + info). Minor omissions like listing supported formats or batch conversion, but sufficient for common tasks.
Related MCP Connectors
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Document-to-Markdown MCP server โ convert PDF, Office and HTML into LLM-ready Markdown.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for seamless document format conversion using Pandoc, supporting Markdown, HTML, PDF, DOCX (.docx), csv and more.1589MIT
- AlicenseBqualityDmaintenanceA universal MCP server for document processing, conversion, and automation. Handle PDF, DOCX, HTML, Markdown, and more through a unified API and toolset.1328 npm140MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that converts Markdown text to DOCX format using an external conversion service. It supports custom templates, multi-language output, and provides flexible file handling for both local and cloud-based deployments.8MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server for converting documents and files to Markdown using Microsoft MarkItDown.MIT