md-server

Convert any document, webpage, or media file to markdown. Works as an HTTP API or directly with AI tools via MCP.

md-server converts files, URLs, or raw content into markdown. It automatically detects input types, handles everything from PDFs and Office documents, YouTube videos, images, to web pages with JavaScript rendering, and requires zero configuration to get started.

Two ways to use it:

• HTTP API — REST API to convert documents and websites to markdown
• MCP Server — Local MCP Server for integration with AI tools (OpenCode, Claude Desktop, Cursor, custom agents)

Under the hood, it uses Microsoft's MarkItDown for document conversion and Crawl4AI for intelligent web scraping.

HTTP API

Prerequisites:

• uv
• (Optional) Install browser for JavaScript-rendered pages: uvx playwright install --with-deps chromium

# Starts server at localhost:8080
uvx md-server

# Convert a file
curl -X POST localhost:8080/convert --data-binary @document.pdf

# Convert a URL
curl -X POST localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Convert HTML text
curl -X POST localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"text": "<h1>Title</h1><p>Content</p>", "mime_type": "text/html"}'

MCP Server for AI Assistants

md-server runs as a local MCP server, giving AI assistants like Claude Desktop, Cursor, Copilot, and OpenCode the ability to read documents and web pages directly.

Prerequisites:

• uv
• (Optional) Install browser for JavaScript-rendered pages: uvx playwright install --with-deps chromium

Add to your MCP configuration:

{
  "mcpServers": {
    "md-server": {
      "command": "uvx",
      "args": ["md-server[mcp]", "--mcp-stdio"]
    }
  }
}

The first run downloads dependencies and may take a minute.

Once configured, your AI gets the read_resource tool:

• Fetch web pages, articles, documentation, online PDFs via URL
• Read uploaded documents (PDF, DOCX, XLSX, PPTX, images with OCR)
• Supports token-based truncation and markdown-aware sectioning

See MCP Guide for all options and troubleshooting.

HTTP API Server Installation

For MCP server setup (AI tools), see MCP Server above.

Using uvx (Recommended)

uvx md-server

Using Docker

The Docker image includes browser support for JavaScript rendering.

docker run -p 127.0.0.1:8080:8080 ghcr.io/peteretelej/md-server

• Memory: 1GB recommended (minimum 512MB)
• Storage: ~1.2GB image size

API

POST /convert

Single endpoint that accepts multiple input types and automatically detects what you're sending.

Input Methods

# Binary file upload
curl -X POST localhost:8080/convert --data-binary @document.pdf

# Multipart form upload
curl -X POST localhost:8080/convert -F "file=@presentation.pptx"

# URL conversion
curl -X POST localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Base64 content
curl -X POST localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"content": "base64_encoded_file_here", "filename": "report.docx"}'

# Raw text
curl -X POST localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"text": "# Already Markdown\n\nBut might need cleaning"}'

# Text with specific format (HTML, XML, etc.)
curl -X POST localhost:8080/convert \
  -H "Content-Type: application/json" \
  -d '{"text": "<h1>HTML Title</h1><p>Convert HTML to markdown</p>", "mime_type": "text/html"}'

Response Format

{
  "success": true,
  "markdown": "# Converted Content\n\nYour markdown here...",
  "metadata": {
    "source_type": "pdf",
    "source_size": 102400,
    "markdown_size": 8192,
    "conversion_time_ms": 245,
    "detected_format": "application/pdf"
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}

Options

{
  "url": "https://example.com",
  "options": {
    "js_rendering": true, // Use headless browser for JavaScript sites
    "extract_images": true, // Extract and link images
    "ocr_enabled": true, // OCR for scanned PDFs/images
    "preserve_formatting": true // Keep complex formatting
  }
}

GET /formats

Returns supported formats and capabilities.

curl localhost:8080/formats

GET /health

Health check endpoint.

curl localhost:8080/health

Supported Formats

Documents: PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP Web: HTML, URLs (with JavaScript rendering) Images: PNG, JPG, JPEG (with OCR) Audio: MP3, WAV (transcription) — requires ffmpeg Video: YouTube URLs Text: TXT, MD, CSV, XML, JSON

Advanced Usage

JavaScript-Rendered Pages

Docker includes browser support out of the box.

Local installations use MarkItDown for URL conversion by default. To read pages that require JavaScript (SPAs, dashboards, interactive apps):

uvx playwright install --with-deps chromium

When a browser is available, md-server automatically uses Crawl4AI for these pages.

Pipe from Other Commands

# Convert HTML from stdin
echo "<h1>Hello</h1>" | curl -X POST localhost:8080/convert \
  --data-binary @- \
  -H "Content-Type: text/html"

# Chain with other tools
pdftotext document.pdf - | curl -X POST localhost:8080/convert \
  --data-binary @-

Python SDK

pip install md-server[sdk]

from md_server.sdk import MDConverter

converter = MDConverter(ocr_enabled=True, js_rendering=True)

# Async
result = await converter.convert_file('document.pdf')
result = await converter.convert_url('https://example.com')
print(result.markdown)

# Sync
result = converter.convert_file_sync('document.pdf')

For remote API usage and advanced patterns, see the Python SDK documentation.

Error Handling

Errors include actionable information:

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FORMAT",
    "message": "File format not supported",
    "details": {
      "detected_format": "application/x-rar",
      "supported_formats": ["pdf", "docx", "html", "..."]
    }
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}

Documentation

Full documentation is available in the docs directory:

• API Reference - HTTP endpoints, options, and responses
• MCP Guide - Claude Desktop, Cursor, and AI tool setup
• Python SDK - Library usage for Python applications
• Configuration - Environment variables reference
• Troubleshooting - Common issues and solutions

Development

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

Powered By

This project makes use of these excellent tools:

License

MIT