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., "@io.github.tidybytetools/doc2md-lite convert ~/Downloads/spring-report.pdf to markdown"
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.
Free tool that turns a text PDF or a saved web page (.html) into clean Markdown. Tables stay real Markdown tables. Need Word files, chunks for AI search (RAG), whole folders or page ranges? The paid version does that: doc2md on Gumroad
Runs on your own computer, so your files are never uploaded anywhere. MIT license. Python 3.10 or newer, on Windows, Mac and Linux.
pip install doc2md-liteOr use pipx, which keeps it in its own space:
pipx install doc2md-liteWant the newest code from GitHub instead?
pip install git+https://github.com/tidybytetools/doc2md-liteRelated MCP server: md-server
doc2md-lite report.pdf # writes report.md
doc2md-lite page.html -o page.md
doc2md-lite report.pdf -o - # print the Markdown on screen
doc2md-lite report.pdf --tables text # also find tables with no border linesExample run:
Saved: report.md (4 headings, 1 tables)What you get from a PDF:
# Spring Store Report
Our team checked every store in March. Most stores met the new goal...
## Sales by region
| Region | Stores | Sales |
| --- | --- | --- |
| North | 12 | $48,200 |
| South | 9 | $39,950 |What it keeps: headings (found by font size and bold in PDFs), paragraphs, bullet and numbered lists, tables, and in HTML also bold, italic, links and code blocks. From web pages it drops scripts, styles, menus and footers.
When you run it in a terminal it ends with one short line about the paid version. --quiet turns it off, and it never shows when output is piped or redirected.
Scanned PDFs. Pages that are just an image (no text layer) are skipped, and the tool tells you which ones.
Headings in PDFs are a best guess from font size and bold. Odd layouts may need a quick fix.
Two-column PDFs (like science papers) may mix the columns.
One file at a time. No folders, no page ranges, no Word files, no RAG chunks. The paid version has those.
Files only. It does not download web pages. Save the page first.
lite (free) | ||
Text PDF and HTML to Markdown | yes | yes |
Tables kept as Markdown tables | yes | yes |
Word (.docx), with bold, italic, links and lists | no | yes |
RAG chunks (JSONL with page, heading path, size and overlap) | no | yes |
Whole folders, sub-folders too | no | yes |
Page ranges and password-protected PDFs | no | yes |
Pick what fits you. MarkItDown reads many more file types. pandoc is great for Word and HTML but does not read PDFs. pymupdf4llm is fast on PDFs but uses the AGPL license. doc2md-lite is small, MIT, keeps PDF tables as tables, and has an MCP server built in.
There is a small free MCP server built in. It gives your AI app one tool, convert_to_markdown. It needs uv.
Run it by hand to check it starts (it waits quietly for an app to talk to it):
uvx --from doc2md-lite doc2md-lite-mcpClaude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"doc2md-lite": {
"command": "uvx",
"args": ["--from", "doc2md-lite", "doc2md-lite-mcp"]
}
}
}Tool: convert_to_markdown(path, tables="lines", output_path=""). It returns the Markdown text. If you set output_path, it saves the file there and returns the path instead.
Use when: you have a local PDF with real text (you can select the words) or a saved HTML file, and you want Markdown to read or store.
Don't use when: the PDF is a scan, the file is .docx, or you need many files or chunks with page numbers. Use the paid version for those.
Input: a file path, plus optional tables (lines, text, off).
Output: Markdown text. Tables are Markdown tables with the first row as the header.
CLI exit code is 0 on success and 1 on error (message on stderr, or {"ok": false, "error": ...} with --json). See also llms.txt.
from doc2md_lite import convert
md, info = convert("report.pdf") # info: type, tables, headings, scanned_pagespip install pdfplumber beautifulsoup4 reportlab "mcp<2"
python3 -m unittest discover testsMIT. See LICENSE.
Turn a local text PDF or saved HTML file into clean Markdown.
path: full path to a .pdf or .html file on this computer. tables: PDF tables. "lines" (default) finds tables with border lines, "text" also tries tables lined up by spaces, "off" gives plain text. output_path: optional. If set, the Markdown is saved there and that path is returned. If empty, the Markdown text is returned.
Tables come back as Markdown tables. Scanned (image-only) PDF pages have no text and are skipped.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| tables | No | lines | |
| output_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that tables become Markdown tables, that image-only pages are skipped rather than erroring, and that output_path changes whether text or a path is returned. It does not cover failure modes for invalid paths or file-size limits, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line purpose followed by per-parameter lines, with the important table-mode detail and the image-only caveat kept short. Every sentence carries information; only slight tightening of the parameter sentences would improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter conversion tool with an output schema, the description covers input types, each parameter's meaning, table handling, and the scanned-page edge case. Nothing critical is missing, though it does not mention error behavior for non-PDF/HTML inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: it defines path as a full path to .pdf/.html, enumerates the three tables modes ('lines' default, 'text', 'off') with their semantics even though the schema declares no enum, and explains output_path's effect. It adds substantial meaning beyond the bare schema, with only minor gaps such as what happens for a missing file.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (convert) and resource (PDF/HTML to Markdown) and constrains the input scope to local text PDFs and saved HTML files. No siblings exist, so no differentiation is needed, and the purpose is unambiguous from the first sentence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies applicability ('local text PDF', 'scanned (image-only) PDF pages have no text and are skipped'), which tells an agent this is not an OCR tool. However there is no explicit when-to-use/when-not guidance or mention of alternatives, so usage is only implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0convert_to_markdownScored across 1 tool
There is only one tool, so there is no possibility of confusion with a sibling tool. Its purpose (file → Markdown conversion) is stated unambiguously.
convert_to_markdown follows a clear verb_noun snake_case convention and is self-descriptive. With a single tool, no inconsistency is possible.
A one-tool 'lite' converter is defensible for the narrow stated purpose, but the surface feels thin — no batch mode and no URL input, so the single entry point carries everything.
Core conversion is covered with sensible options (table mode, output path), but obvious gaps remain: no URL fetching, no batch conversion, and scanned/image-only PDFs are silently skipped with no OCR fallback.
Convert PDF, DOCX, HTML, and URLs to clean, LLM-ready markdown with tables preserved
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
Clean, repair, and convert AI-generated Markdown to HTML/PDF/DOCX/PNG; save and share documents.
