ezmd MCP server

ezmd

Anything in. Clean Markdown out. ezmd turns PDFs, Office files, web pages, data files, code and archives into Markdown that AI models read well, keeps a record of where every part came from, and tells you what it could not convert.

<!-- readme: skip (installs from the network) -->

pip install ezmd                       # Python 3.12 or newer; or: uv tool install ezmd
ezmd convert paper.pdf                 # Markdown on stdout, warnings on stderr
ezmd convert https://example.com -o page.md

Apache-2.0. Runs on a CPU with no model downloads. Works as a CLI, a Python library, an MCP server for Claude, Cursor and other agents, a REST API with a web UI, and a self-hosted Docker stack.

What you get

Converting the Mamba paper (36 pages, CC BY 4.0) with the default install takes about four seconds and gives one Markdown file:

---
title: "Mamba: Linear-Time Sequence Modeling with Selective State Spaces"
source: "mamba.pdf"
source_type: pdf
pages: 36
word_count: 22409
tokens: {o200k_base: 44058, cl100k_base: 44292, claude_approx: 47583}
warnings: [removed_script_or_macro, engine_fallback, removed_running_header_footer, injection_suspected]
---
# Mamba: Linear-Time Sequence Modeling with Selective State Spaces

## 1 Introduction {#sec-1}
...
## 3 Selective State Space Models {#sec-3}
### 3.1 Motivation: Selection as a Means of Compression {#sec-3-1}

Every conversion comes with three things:

content hash, and the list of warning codes. An agent can decide what to do with a document before reading it.

• A header of facts. Title, source, page count, word count, token counts under three tokenizers, a

superscripts stay superscripts (10²⁰, not 1020), lists stay lists, links keep their targets. Running headers, footers and page numbers are removed; words broken across lines are joined.

• Structure, kept. Headings follow the document's own outline, with anchors. Tables stay tables,

a count, the pages involved and a suggestion: pages with no text layer, glyphs the PDF's fonts cannot map to text, a table that lost its header, content that looks like instructions to an AI. The full list is in docs/warnings.md.

• Warnings, not silence. Everything ezmd detects it could not convert becomes a warning with a code,

With --sidecar, a JSON file beside the Markdown records the page and position of every block, so answers can cite the page they came from.

Use it from

The command line

<!-- readme: run -->

uv run ezmd convert fixtures/office/docx-review/input.docx --profile compact
uv run ezmd convert fixtures/pdf/born-digital-report/input.pdf --profile rag
uv run ezmd convert fixtures/text/markdown-kitchen-sink/input.md --json
uv run ezmd detect fixtures/pdf/born-digital-report/input.pdf
uv run ezmd batch fixtures/text --recursive --out out/text

The commands above run from a source checkout and use files from fixtures/, so you can paste them as they are; installed, drop the uv run. Warnings go to stderr as WARN [code] message. ezmd batch skips unchanged inputs when run again. URLs are fetched through an SSRF guard that refuses private and loopback addresses:

<!-- readme: skip (needs network access) -->

uv run ezmd convert https://example.com --profile compact

Every command and option: docs/cli.md.

Python

<!-- readme: run -->

import ezmd

Shortened. The full README is on GitHub.