any2markdown

Any2Markdown is a high-performance MCP server that exposes both the MCP protocol (streaming image-rich document conversion via the MCP client) and a RESTful API for converting documents to Markdown, HTML, or JSON. It supports converting PDFs, Word documents, and Excel sheets into structured Markdown with features like image extraction, header/footer removal, and batch processing. Clients can connect via the MCP protocol for streaming-style conversion or use the REST API endpoints to upload files or send base64-encoded content. The server provides an OpenAPI/Swagger document for API exploration and a set of tools/endpoints for converting documents and analyzing document structure. Typical workflows include uploading a document to the REST API for conversion or using the MCP client to request conversion tasks in a streaming fashion, receiving results as they are produced, and leveraging the bundled tools for PDFs, Word, and Excel formats.

Prerequisites:

• Python 3.10–3.13 installed on the host (as validated by the project).
• 4 GB+ RAM and 10 GB+ disk space for model caches and temporary files.
• Network access for downloading models and dependencies.

Installation steps:

1. Clone the repository:

git clone https://github.com/WW-AI-Lab/any2markdown.git
cd any2markdown

2. Create and activate a virtual environment (recommended):

python3.13 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Prepare environment and install dependencies:

cp env.example .env
# Install dependencies (using Huawei mirror if desired)
PIP_CONFIG_FILE=.pip/pip.conf pip install -r requirements.txt

4. Or run the provided deployment script (if available):

./scripts/setup_venv.sh
./scripts/deploy.sh source

5. Start the server (from project root):

# Ensure virtual environment is active
python run_server.py

6. Verify that the server is accessible:

• MCP endpoint: http://localhost:3000/mcp
• REST API: http://localhost:3000/api/v1/
• API docs: http://localhost:3000/api/v1/docs

Notes:

• If using Docker, follow the Docker deployment instructions in README to run with a container.
• Prepare environment variables in a .env file or via the mcp_config.env mapping as needed.

Tips and common issues:

• Ensure that the model caches directories exist and are writable, e.g., ~/.cache/marker and related HF cache paths.
• When enabling GPU acceleration, install the appropriate CUDA drivers and ensure the host has a compatible NVIDIA GPU.
• For large documents, consider increasing MAX_CONCURRENT_JOBS and ensuring enough CPU/GPU resources are available.
• If images should be served from a static URL, configure the image extraction feature and hosting path accordingly.
• Review the API docs at /api/v1/docs to understand request payloads for file uploads and base64-encoded content.
• If you run into port conflicts, adjust MCP_SERVER_PORT in the environment or the command invocation.