Markitdown Webui2

MarkItDown WebUI 2

[English](README.md) | [简体中文](README.zh-CN.md)

Local document-to-Markdown WebUI with image OCR and automatic MCP integration for Claude Code, Codex, and Hermes Agent.

• Private local WebUI at http://localhost:5001
• Microsoft MarkItDown for PDF, Office, HTML, data, and text files
• Unlimited-OCR MLX Int4 for layout-aware OCR on Apple Silicon
• RapidOCR PP-OCRv6 Small with NVIDIA CUDA and automatic CPU fallback on Windows
• Tesseract fallback for fast Chinese and English OCR
• A local stdio MCP server with no API key and no cloud upload

One-command install (macOS)

curl -fsSL https://raw.githubusercontent.com/nfeuism/markitdown-webui2/main/scripts/bootstrap.sh | bash

安装完成后打开：

open http://localhost:5001

The installer automatically:

1. installs uv when needed and creates an isolated Python 3.12 runtime;
2. installs the WebUI, MarkItDown, and MCP server dependencies;
3. installs the Apple Silicon MLX OCR runtime;
4. downloads and caches the approximately 2.35 GB local OCR model;
5. installs Tesseract language data when Homebrew is available;
6. starts a private macOS LaunchAgent that survives login and crashes;
7. registers the MCP server in every supported agent CLI found on the Mac.

The command is safe to run again to update or repair an installation. If you prefer to inspect scripts before executing them, clone the repository and run ./install.sh locally.

One-command install (Windows)

Open PowerShell and run:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/nfeuism/markitdown-webui2/main/scripts/bootstrap.ps1 | iex"

Then open the WebUI:

Start-Process http://localhost:5001

The installer detects nvidia-smi. On a supported NVIDIA system it installs ONNX Runtime CUDA for the bundled PP-OCRv6 Small Chinese/English models. If CUDA is unavailable or GPU inference fails, Auto immediately retries the same small models on CPU. A PC without NVIDIA hardware installs the CPU runtime directly. See the [Chinese guide](README.zh-CN.md) for prerequisites, management commands, MCP setup, and troubleshooting.

WebUI workflow

1. Drag in a document, screenshot, or scanned image.
2. For images, keep OCR engine → Auto unless you need to force an engine.
3. Review the Markdown preview.
4. Select Download Markdown.

On Apple Silicon, Auto uses Unlimited-OCR first. On Windows, it tries RapidOCR NVIDIA CUDA, then RapidOCR CPU. Tesseract remains the final fallback when installed. Supported images are JPG, PNG, WebP, BMP, and TIFF. Other supported inputs include PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, TXT, and Markdown.

Agent MCP integration

The same installer checks for these commands and registers a user-level stdio server named markitdown-webui2:

| Client | Registration used by the installer | |---|---| | Codex | codex mcp add markitdown-webui2 -- …/python …/mcp_server.py | | Claude Code | claude mcp add --scope user --transport stdio markitdown-webui2 -- … | | Hermes Agent | hermes mcp add markitdown-webui2 --command …/python --args …/mcp_server.py |

Restart an already-running agent session after installation. You can then ask:

Use markitdown-webui2 to OCR ~/Desktop/receipt.png and save the Markdown next to it.

The MCP server exposes:

| Tool | Purpose | |---|---| | ocr_status | Show available OCR engines and model-cache state. | | convert_file | Convert any supported local document or image. | | ocr_image | OCR an image with Auto, Unlimited-OCR, RapidOCR GPU/CPU, or Tesseract. |

Re-register installed clients at any time:

~/Library/Application\ Support/MarkItDownWebUI2/runtime/install-mcp.sh

On Windows:

& "$env:LOCALAPPDATA\MarkItDownWebUI2\runtime\install-mcp.ps1"

This setup follows the current stdio MCP configuration documented by Codex, Claude Code, and Hermes Agent.

Status and controls

When installed with the one-command setup:

RUNTIME="$HOME/Library/Application Support/MarkItDownWebUI2/runtime"
"$RUNTIME/status.sh"
"$RUNTIME/restart.sh"
"$RUNTIME/stop.sh"
"$RUNTIME/start.sh"
"$RUNTIME/uninstall.sh"

The health endpoints are:

curl http://localhost:5001/health
curl http://localhost:5001/api/ocr-capabilities

Installer options

Environment variables can change the defaults:

# Use another port and upload limit
PORT=5055 MAX_FILE_SIZE_MB=250 ./install.sh

# Install without downloading the model immediately
DOWNLOAD_OCR_MODEL=0 ./install.sh

# Skip agent MCP registration
INSTALL_MCP=0 ./install.sh

# Use another compatible MLX vision model
MARKITDOWN_OCR_MODEL=owner/model ./install.sh

Unlimited-OCR through MLX requires an Apple Silicon Mac. Other Macs can use Tesseract when it is installed. The WebUI binds only to 127.0.0.1; it is not exposed to the LAN or internet.

Manual development setup (macOS)

git clone https://github.com/nfeuism/markitdown-webui2.git
cd markitdown-webui2
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt -r requirements-local-ocr.txt
.venv/bin/python serve.py

Run checks:

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall app.py converter_service.py local_ocr.py mcp_server.py
bash -n install.sh install-mcp.sh scripts/bootstrap.sh

Storage and privacy

• Runtime: ~/Library/Application Support/MarkItDownWebUI2/runtime
• Source managed by the bootstrapper: ~/Library/Application Support/MarkItDownWebUI2/source
• Model cache: ~/.cache/huggingface
• Service log: ~/Library/Application Support/MarkItDownWebUI2/runtime/logs/webui.log
• Temporary uploads: automatically eligible for cleanup after one hour

OCR and conversion happen locally. The application does not require an API key and does not upload input files to an external service. The first model install downloads model files from Hugging Face.

Acknowledgements

Built around Microsoft MarkItDown, Baidu Unlimited-OCR, RapidOCR, MLX, ONNX Runtime, and Tesseract. This repository is independently maintained and is not a GitHub fork.

License

MIT. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nfeuism
• Source: nfeuism/markitdown-webui2
• License: MIT

Install and usage instructions live in the source repository linked above.