Any file to Markdown.

Install it your way

Three install paths, same binary. The shell script is the fastest route; the package managers work if you already live in Bun or Node. Then run the sanity checks before you convert anything.

# one-line install curl -fsSL https://raw.githubusercontent.com/ojspace/md-anything/main/install.sh | bash # …or via a package manager bun install -g md-anything npm install -g md-anything # sanity: help + environment check mda --help mda doctor

Four commands that cover most days

Convert a single file, a PDF, a web article, or a whole directory. Recursive ingest takes an input folder and an output folder; everything else prints or writes Markdown plus a structured JSON envelope on request.

# plain text → Markdown mda tests/fixtures/sample.txt # PDF → Markdown mda convert report.pdf # web article → Markdown mda convert "https://example.com/article" # whole folder, recursive, into ./output mda ingest ./notes -o ./output -r # check the toolchain, browse samples, take the tour mda doctor mda examples mda demo

Three tiers, no surprises

Every input lands in exactly one tier. Strong means it works out of the box. Best-effort means it works when the source cooperates or a small local dependency is present. Optional means you bring an extra tool — Calibre, whisper, ffmpeg — and md-anything does the rest. The envelope always tells you which tier handled your file via its supportLevel field.

Input	Level	Notes
txt / md / json / html	Strong	Plain text, Markdown, JSON and HTML convert directly with no extra setup.
http(s) URLs	Strong	Web articles and pages fetched over http(s) and returned as clean Markdown.
PDF	Strong	unpdf is the default engine; pdftotext is supported as an optional drop-in.
YouTube transcripts	Best-effort	Uses the video's published transcript when one exists; no transcript, no text — nothing is invented.
Images	Best-effort	Metadata-only by default; full text extraction needs OCR via tesseract installed locally.
EPUB	Best-effort	Handled when unzip is available on the machine to unpack the archive.
mobi / azw	Optional	Requires Calibre's conversion tools on your PATH.
Audio / video	Optional	Transcribed locally with whisper-cpp or whisper plus ffmpeg; opt-in OpenRouter fallback when local transcription is not available.

Not sure what your machine can handle today? Run mda doctor — it reports which engines and optional dependencies are present before you convert.

Commands

Seven verbs cover the whole tool. Convert for single inputs, ingest for directories, doctor for diagnostics, examples and demo for learning, and mcp install to wire the agent server in one step.

Command	What it does
mda <file>	Convert a single file straight to Markdown.
mda convert <input>	Convert a file or http(s) URL; add --json for the structured envelope.
mda ingest <dir>	Convert a whole directory; pair with -o for the output folder and -r to recurse.
mda doctor	Check the local toolchain and report which engines are available.
mda examples	Print sample commands to learn the CLI by copying.
mda demo	Guided tour of what the tool can do.
mda mcp install	One-command MCP setup for your agent client (see § 04).

Flags

Four flags modify conversion output. The --json flag is the pipeline flag: it swaps human-readable Markdown for a machine-readable envelope.

Flag	Effect
-o / --output	Write results to a file or directory instead of stdout.
--no-frontmatter	Drop the YAML frontmatter block from the Markdown output.
--json	Return the structured envelope instead of plain Markdown.
-r / --recursive	Walk input directories recursively (used with ingest).

The --json envelope

Scripts and agents should parse this, not the Markdown. Eight fields, always the same shape:

{ "input", "markdown", "kind", "supportLevel", "chunks", "metadata", "provenance", "warnings" }

supportLevel tells you which tier from § 02 handled the file; provenance records where the text came from; warnings flag anything the converter wants you to know — a missing transcript, a metadata-only image, a fallback engine.

One command per client

The stdio MCP server ships in the same package. Point the installer at your agent client and it registers everything — tools, resources and prompts — in a single step.

mda mcp install claude|claude-code|cursor|windsurf|vscode|antigravity|opencode

1. Pick your client. Replace the last argument with exactly one name: claude, claude-code, cursor, windsurf, vscode, antigravity or opencode.
2. Run it once. The installer registers the stdio server with that client — no hand-edited JSON config, no port juggling.
3. Ask your agent. Conversion, folder ingest and diagnostics are now tools the model can call on its own.

Tools, resources, prompts

Three tools do the work; one resource exposes diagnostics; two prompts bundle common document workflows.

Surface	Name	Use it for
Tool	convert	Convert a single file or URL from inside the agent.
Tool	ingest	Convert a directory of documents in one call.
Tool	doctor	Let the agent check the local toolchain itself.
Resource	md-anything://doctor	Machine-readable diagnostics the agent can read before converting.
Prompt	analyze_document	Pre-built prompt for deep analysis of a converted document.
Prompt	summarize_document_chunks	Pre-built prompt for summarizing chunked conversion output.

Safety rules, all four of them

The server is fenced in by default. Agents get document access, not filesystem or network freedom.

#	Rule
01	Workspace-root paths only — the server refuses anything outside the project root.
02	http(s) URLs only — no other schemes are fetched, ever.
03	Private and localhost addresses are blocked by default.
04	Set MDA_MCP_ALLOW_PRIVATE_URLS=1 to lift rule 03 — an explicit, logged opt-in, not an accident.

Questions worth asking before you install

Each answer stays inside what the README verifies. No invented benchmarks, no download counts, no promises about formats on the roadmap.

Is it really local-first? Does the core need the cloud?

Yes. The core conversion path needs no cloud account and no API key: text, HTML, URLs, PDFs, EPUBs and images all convert on your machine. The single exception is audio/video, where an opt-in OpenRouter fallback exists for when local transcription is unavailable. Everything else — including the MCP server — runs over stdio on localhost.

How is this different from cloud document converters?

Cloud converters upload your files to someone else's infrastructure and usually charge per page. md-anything runs where your files already are, is MIT open source so you can read every line, emits both Markdown and a structured JSON envelope with provenance and warnings, and meets agents halfway with a native MCP server instead of a REST API you have to wrap yourself.

What happens with a YouTube video that has no transcript?

YouTube support is honestly best-effort: if the video published a transcript, md-anything converts it. If no transcript exists, there is no text to convert, and you get an honest fallback instead of hallucinated content. When you have the actual media file, local transcription via whisper-cpp or whisper plus ffmpeg is the supported path to real words.

Should my agent use the MCP server or the CLI with --json?

If the agent speaks MCP, use the server: one install command registers convert, ingest and doctor as callable tools plus the doctor resource and two document prompts. If you are scripting pipelines, cron jobs or shell loops, use the CLI — convert --json returns the fixed eight-field envelope (input, markdown, kind, supportLevel, chunks, metadata, provenance, warnings) that jq and every JSON parser already understand.

How can I contribute?

On GitHub at github.com/ojspace/md-anything — issues and pull requests are welcome. Before filing, run mda doctor to capture your environment, mda examples for the canonical command shapes, and mda demo for the tour. The stated vision is to become the default open-source layer for document ingestion in agent pipelines, with DOCX/PPTX support, streaming, semantic chunking, watch mode and Python/Go SDKs on the roadmap — all fair game for contributors.

How this page was checked

Every claim above comes from the project's GitHub README at github.com/ojspace/md-anything, verified Sep 2026: the one-liner, the two surfaces (mda CLI + md-anything-mcp stdio server), all three install paths, the quick commands, the strong / best-effort / optional tiers with their exact engines and dependencies, the four CLI flags, the eight-field --json envelope, the one-command MCP setup strings, the three tools plus doctor resource and two prompts, and the four safety rules including the MDA_MCP_ALLOW_PRIVATE_URLS=1 override. Standing and download counts are intentionally not shown — they go stale and prove nothing about whether the tool works. The vision and roadmap lines (default open-source ingestion layer; DOCX/PPTX, streaming, semantic chunking, watch mode, Python/Go SDKs) are the project's own stated direction, not shipped features.

Keep exploring

More from the same lab.