Skip to main content
Glama
riyengar19

md-converter-mcp

by riyengar19
OverviewSchemaRelated ServersScoreDiscussions
Local

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: md-server

What it does

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

Input

How

PDF

pdf-parse — text extraction, no rendering

DOCX

mammoth

PPTX

adm-zip + fast-xml-parser (slide XML → text)

XLSX / XLS

xlsx (sheet → Markdown table)

PNG, JPG, JPEG, WEBP, TIFF, BMP

tesseract.js OCR

HTTP/HTTPS URL

node-fetch + cheerio (HTML → structured Markdown)

TXT / MD

Raw file 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.

Document

Pages

MCP tokens

Direct upload tokens

Reduction

Sales enablement deck (12-page presentation PDF)

12

1,399

19,399

93%

Technical user guide (16-page dense doc)

16

6,309

30,309

79%

Web article saved as PDF (6 pages)

6

1,593

10,593

85%

Medical report (3-page)

3

~680

~5,200

87%

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

Node version

Status

18.x LTS

✅ Tested

20.x LTS

✅ Tested

22.x LTS

✅ Tested

16.x

⚠️ May work, not supported

Dependencies

Package

Purpose

@modelcontextprotocol/sdk

MCP server + stdio transport

pdf-parse

PDF text extraction

mammoth

DOCX → plain text

adm-zip + fast-xml-parser

PPTX slide XML extraction

xlsx

Excel → Markdown tables

tesseract.js

OCR for images

node-fetch

HTTP fetching for URLs

cheerio

HTML → structured Markdown

zod

Input validation

License

GPL-3.0 — see LICENSE.

Available Tools

1 tool
convert_to_markdownA

Convert a file or URL to Markdown. Supports PDF, DOCX, PPTX, XLSX/XLS, images (OCR via Tesseract), and web pages. Automatically logs token savings to a local database — view the dashboard at http://localhost:3847. Pass an absolute file path or an HTTP/HTTPS URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesAbsolute file path or HTTP/HTTPS URL to convert

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It reveals a side effect: 'Automatically logs token savings to a local database' and exposes a dashboard URL. However, it does not specify the return format (e.g., whether Markdown is returned as a string or written to a file), nor does it mention dependencies like Tesseract installation or network access for URLs, leaving some behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four concise sentences, front-loaded with the core purpose. Each sentence contributes distinct information: purpose, supported formats, side-effect/logging, and invocation instruction. There is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple one-parameter tool, but without an output schema, the description should clarify what the conversion produces. It fails to state whether the Markdown is returned inline, saved to a file, or delivered via the dashboard, and doesn't mention input size limits or error conditions. The logging side effect is disclosed, but the absence of return semantics is a notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the 'input' parameter as 'Absolute file path or HTTP/HTTPS URL to convert' with 100% coverage, giving a baseline of 3. The description adds value by enumerating supported file types and noting that images use OCR, clarifying valid input categories beyond the generic path/URL description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: 'Convert a file or URL to Markdown.' It enumerates supported input types (PDF, DOCX, PPTX, XLSX/XLS, images with OCR, web pages), making the purpose unambiguous. Even without siblings, the scope is specific and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool by listing supported formats and instructs to 'Pass an absolute file path or an HTTP/HTTPS URL.' It lacks explicit exclusions or alternative tools, but the supported-format list provides clear context for typical conversion tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.1.0
    • First observedconvert_to_markdown
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusing it with another. The tool's purpose is clear and distinct.

Naming Consistency5/5

The single tool name 'convert_to_markdown' follows a clear verb_noun pattern and is descriptive. Consistency is trivially maintained with one tool.

Tool Count3/5

The server has exactly one tool, which feels borderline for a converter that supports many formats. While it could be sufficient, a single tool may limit flexibility for advanced use cases.

Completeness5/5

The tool covers the primary domain of converting various file types and URLs to Markdown, including OCR and web pages. No obvious gaps in the conversion workflow are apparent.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/riyengar19/md-converter-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server