md

md-server is a local MCP server that enables AI tools to read documents, web pages, and other content by converting them to markdown. It supports a wide range of input types (files, URLs, raw text, and content requiring JavaScript rendering) and exposes a read_resource capability via the MCP protocol, allowing agents like Claude Desktop, Cursor, Copilot, and OpenCode to access extracted markdown content and metadata. When running with MCP, you enable the md-server as an MCP endpoint and your AI tools can request read operations through the provided tool interface and options (e.g., enabling OCR, JS rendering, or preserving formatting). The server can automatically detect input types and handles PDFs, Office documents, images, web pages, and more, leveraging MarkItDown for conversion and Crawl4AI for intelligent web scraping when needed.

Prerequisites:

• Python 3.10+ (recommended) and uv (the microserver runner)
• Optional: a browser for JavaScript-rendered pages when using md-server with JS-heavy sites

Install via MCP workflow:

1. Install uvx (the MCP server runner) if you don’t have it installed:
   • Follow UV installation guidelines for your platform (https://docs.astral.sh/uv/getting-started/installation/)
2. Install the md-server package (as needed for your environment). If you plan to run via npm/py, follow the project’s installation notes in the repository:
   • Typically, you would install and run through uvx with the server entry point as shown in the MCP guide.
3. Start the server (example with uvx):
   • uvx md-server[mcp] --mcp-stdio
4. Verify the server is running at the expected port (default 8080 or as configured by your environment).

If you prefer Docker:

• Run the Docker image that includes browser support for JavaScript rendering: docker run -p 127.0.0.1:8080:8080 ghcr.io/peteretelej/md-server

Prerequisites are primarily Python and uv for MCP usage; for HTTP API usage or MCP integration, ensure your environment variables (if any) are configured per your MCP setup.

Tips and common notes:

• For MCP usage, add the md-server MCP configuration in your environment to expose the read_resource tool to your AI assistants.
• If you enable JS rendering, ensure you have a browser installed (uvx playwright) to handle dynamic pages.
• When using OCR for images or scanned PDFs, allocate enough memory (1GB+ recommended) since rendering and OCR can be resource-intensive.
• Check the MCP documentation for details on options like read_resource parameters, truncation, and markdown-aware sectioning to tailor how content is extracted and chunked for your agents.
• If you encounter issues with input type detection, verify that the API call or MCP command includes the correct payload (URL, file, or text) and that the server has access to the content.