DHIVA LABS · LEARN

Appearance

MCP connector ​

markdrop-mcp is a server for the Model Context Protocol (MCP), an open standard that lets apps use outside tools. Once you connect it to an MCP client, such as Claude Desktop or Claude Code, the client can convert files, whole folders, web pages and YouTube videos to Markdown on your computer.

Install ​

You need Python 3.10 or newer.

  1. Download markdrop_mcp-0.1.0-py3-none-any.whl from the latest release.

  2. Install it:

    bash
    pip install markdrop_mcp-0.1.0-py3-none-any.whl

    This adds the markdrop-mcp command.

Connect it to a client ​

Claude Code ​

bash
claude mcp add markdrop -- markdrop-mcp --root ~/your-folder

Replace ~/your-folder with the folder whose files you want to convert.

Claude Desktop ​

Add an entry to claude_desktop_config.json and restart the app:

json
{
  "mcpServers": {
    "markdrop": {
      "command": "markdrop-mcp",
      "args": ["--root", "/home/you/Documents"]
    }
  }
}

If the app cannot find markdrop-mcp, use its full path, which which markdrop-mcp prints.

Tools ​

ToolWhat it does
convert_fileConverts a local file. Can save the result to output_path.
convert_urlConverts a web page or a linked file. Can save to output_path.
convert_to_markdownConverts a file:, http:, https: or data: address.
youtube_to_markdownGets a video's details and transcript, with include_timestamps for [hh:mm:ss] times.
convert_directoryConverts every matching file in a folder, optionally filtered by glob, into .md files in output_dir, and returns a summary.
list_supported_formatsLists the formats it can convert and the folders it may read.

You do not call these yourself. Ask the client in plain words, for example "convert the PDFs in my reports folder to Markdown", and it picks the tool.

Which folders it can read ​

markdrop-mcp only reads files inside allowed roots. By default these are the folder it was started in, ~/Documents and ~/Downloads.

  • Give one or more folders with --root DIR. You can repeat it.
  • Or set MD_MCP_ROOTS to a list separated by colons, such as /home/you/notes:/home/you/papers.

The check follows the real location of every path, so a link inside an allowed folder cannot point it at a file outside.

Limits ​

  • Web addresses on private or local networks are refused, and every redirect is checked.
  • Downloads from the web are limited to 50 MB.
  • Results returned directly to the client are cut at 100,000 characters (MD_MCP_MAX_INLINE_CHARS). When you ask for an output_path, the complete file is always written.

Run it over HTTP ​

By default the client starts markdrop-mcp itself and talks to it directly. To run it as a network service instead:

bash
MD_MCP_TOKEN=<token> markdrop-mcp --http --host 127.0.0.1 --port 3002

The endpoint is http://127.0.0.1:3002/mcp, and clients must send Authorization: Bearer <token>.

WARNING

Always set MD_MCP_TOKEN in HTTP mode. Without it, anyone who can reach the port can read files in your allowed roots. Keep --host 127.0.0.1 unless you need access from other machines, and then only on networks you trust.

Command-line options ​

OptionDefaultWhat it does
--root DIRCurrent folder, ~/Documents, ~/DownloadsAllows file access under DIR. Repeat for more folders.
--httpOffServes over HTTP instead of talking directly to one client.
--host127.0.0.1The address to listen on in HTTP mode.
--port3002The port to listen on in HTTP mode.

Next steps ​