Content
# 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)
```bash
curl -fsSL https://raw.githubusercontent.com/nfeuism/markitdown-webui2/main/scripts/bootstrap.sh | bash
```
安装完成后打开：
```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
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/nfeuism/markitdown-webui2/main/scripts/bootstrap.ps1 | iex"
```
Then open the WebUI:
```powershell
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:
```text
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:
```bash
~/Library/Application\ Support/MarkItDownWebUI2/runtime/install-mcp.sh
```
On Windows:
```powershell
& "$env:LOCALAPPDATA\MarkItDownWebUI2\runtime\install-mcp.ps1"
```
This setup follows the current stdio MCP configuration documented by
[Codex](https://developers.openai.com/codex/mcp/),
[Claude Code](https://code.claude.com/docs/en/mcp), and
[Hermes Agent](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/mcp.md).
## Status and controls
When installed with the one-command setup:
```bash
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:
```bash
curl http://localhost:5001/health
curl http://localhost:5001/api/ocr-capabilities
```
## Installer options
Environment variables can change the defaults:
```bash
# 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)
```bash
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:
```bash
.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](https://github.com/microsoft/markitdown),
[Baidu Unlimited-OCR](https://huggingface.co/baidu/Unlimited-OCR),
[RapidOCR](https://github.com/RapidAI/RapidOCR), MLX, ONNX Runtime, and
Tesseract. This repository is independently maintained and is not a GitHub fork.
## License
MIT. See [LICENSE](LICENSE).
