md-anything

md-anything

Convert files, URLs, and media into honest Markdown for terminal workflows and MCP-powered agents.

md-anything currently ships two surfaces:

• a local-first CLI: mda
• a stdio MCP server: md-anything-mcp

Install

curl -fsSL https://raw.githubusercontent.com/ojspace/md-anything/main/install.sh | bash

Or install globally with Bun or npm:

bun install -g md-anything
npm install -g md-anything

Quick sanity check:

mda --help
mda doctor

Quick start

# Convert one file or URL
mda tests/fixtures/sample.txt
mda convert report.pdf
mda convert "https://example.com/article"

# Batch-convert a folder
mda ingest ./notes -o ./output -r

# Check optional tool availability
mda doctor

# Copy-paste examples
mda examples
mda demo

What is supported

md-anything uses three support levels:

• strong: works well out of the box
• best-effort: useful, but quality depends on content and local tools
• optional: requires extra tools or an opt-in remote fallback

Input	Support	Notes
.txt, .md, .markdown, .json, .html, .htm	strong	Native or straightforward extraction
http:// / https:// URLs	strong	Fetch + HTML extraction
.pdf	strong	unpdf by default, pdftotext can improve some files
YouTube URLs	best-effort	Transcript-first, honest fallback when unavailable
Images (.png, .jpg, .webp, .gif, etc.)	best-effort	Metadata-only by default, OCR with tesseract, richer remote fallback via OpenRouter
.epub	best-effort	Extraction depends on unzip; doctor will tell you if it is missing
.mobi, .azw	best-effort	Requires Calibre ebook-convert
Audio (.mp3, .wav, etc.)	optional	Local whisper-cpp or whisper, optional OpenRouter fallback
Video (.mp4, .mov, etc.)	optional	Requires ffmpeg plus whisper-cpp / whisper, optional OpenRouter fallback

CLI reference

# Single input
mda <input>
mda convert <input>

# Write Markdown to a file
mda convert report.pdf -o report.md

# Omit frontmatter
mda convert report.pdf --no-frontmatter

# Machine-readable JSON
mda convert report.pdf --json

# Batch-convert a folder
mda ingest ./notes
mda ingest ./notes -o ./output
mda ingest ./vault -r -o ./output

# Environment/capability checks
mda doctor

# Help and examples
mda --help
mda examples
mda demo

Flags

Flag	Description
-o, --output <path>	Output file for convert or output directory for ingest
--no-frontmatter	Omit YAML frontmatter from generated Markdown
--json	Return machine-readable JSON instead of Markdown
-r, --recursive	Recurse into subdirectories during ingest
-h, --help	Show help

JSON output

convert --json returns a stable machine-readable envelope:

mda convert report.pdf --json

{
  "input": "report.pdf",
  "markdown": "# Report Title\n...",
  "kind": "pdf",
  "supportLevel": "strong",
  "chunks": [],
  "metadata": {
    "extraction": "unpdf",
    "extraction_status": "ok",
    "support_level": "strong",
    "usefulness_score": 0.85
  },
  "provenance": {
    "documentId": "..."
  },
  "warnings": []
}

ingest --json returns counts plus per-document metadata:

mda ingest ./notes --json

{
  "converted": 12,
  "skipped": 2,
  "failed": 0,
  "docs": [
    {
      "fileName": "note.md",
      "title": "My Note",
      "summary": "This is a summary of the note.",
      "sourceType": "pdf",
      "source": "report.pdf",
      "chunks": [],
      "metadata": {
        "extraction_status": "ok"
      },
      "provenance": {
        "documentId": "..."
      }
    }
  ]
}

Argument errors stay machine-readable too:

{
  "error": "Missing input for convert command.",
  "code": "missing_input",
  "examples": [
    "mda convert tests/fixtures/sample.txt",
    "mda convert \"https://example.com/article\""
  ]
}

MCP server

One-command setup