md-converter-mcp

A Node.js MCP server that converts files and URLs to Markdown — exposes a single convert_to_markdown tool that any MCP-compatible AI client (Claude Desktop, Cursor, VS Code, etc.) can call directly.

Requires Node.js ≥ 18. No Python. No Docker.

Why this exists

Microsoft's markitdown-mcp is a great idea but fails to install on Python 3.13+ due to unresolved wheel conflicts in its dependency tree (youtube-transcript-api and others). If you hit errors like:

ERROR: Could not find a version that satisfies the requirement ...

…this is a pure Node.js drop-in that does the same job without touching Python at all.

Related MCP server: Markdownify MCP Server

What it does

Converts any of these inputs into clean Markdown text that the AI can read:

Token savings vs. direct file upload

When you drop a PDF directly into Claude, each page is rendered as an image and processed through the vision layer at ~1,500 tokens/page. This MCP extracts plain text on your machine before anything crosses the API boundary.

Installation

Prerequisites: Node.js 18+ (LTS recommended)

# 1. Clone the repo
git clone https://github.com/raghunath-iyengar/md-converter-mcp.git
cd md-converter-mcp

# 2. Install dependencies
npm install

That's it. No build step, no compile step.

Verify it works

node server.js

You should see the process start and wait (it listens on stdio for MCP messages). Press Ctrl+C to exit.

Connect to Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the md-converter block inside mcpServers:

{
  "mcpServers": {
    "md-converter": {
      "command": "node",
      "args": ["/absolute/path/to/md-converter-mcp/server.js"]
    }
  }
}

Replace /absolute/path/to/md-converter-mcp/server.js with the actual path on your machine.

macOS example:

"args": ["/Users/yourname/md-converter-mcp/server.js"]

Windows example:

"args": ["C:\\Users\\yourname\\md-converter-mcp\\server.js"]

Restart Claude Desktop. You should see md-converter appear in the MCP tools list.

Connect to other MCP clients

Any client that supports the MCP stdio transport works. The server command is always:

node /path/to/server.js

Cursor / VS Code (.cursor/mcp.json or mcp.json)

{
  "mcpServers": {
    "md-converter": {
      "command": "node",
      "args": ["/path/to/md-converter-mcp/server.js"]
    }
  }
}

Usage

Once connected, tell Claude (or any MCP client) to use the tool:

"Use convert_to_markdown to read /Users/yourname/Documents/report.pdf"

Or just drop a file reference in your message — Claude will call the tool automatically when it needs to read a supported file type.

URL example:

"Summarise https://example.com/article using convert_to_markdown"

Troubleshooting

node: command not found Node.js is not in PATH. Use the full path to the node binary in your config:

"command": "/usr/local/bin/node"

Find it with which node (macOS/Linux) or where node (Windows).

Error: File not found The MCP server runs as a subprocess — it does not inherit your shell's working directory. Always pass absolute paths, not relative ones.

pdf-parse warning about test files Safe to ignore. It's a known cosmetic warning in pdf-parse v1.x that does not affect output.

Tesseract OCR is slow on first run tesseract.js downloads language data on first use and caches it. Subsequent calls are fast.

Claude Desktop shows MCP connection error Check the config JSON for syntax errors (trailing commas are invalid JSON). Validate with node -e "JSON.parse(require('fs').readFileSync('claude_desktop_config.json','utf8'))".

Supported Node versions

Dependencies

License

GPL-3.0 — see LICENSE.