GitHub - levz0r/html-to-markdown-mcp: MCP server for converting HTML to Markdown using Turndown.js. Fetch web pages and convert them to clean, formatted Markdown. (original) (raw)

HTML to Markdown MCP Server

npm version npm downloads

An MCP (Model Context Protocol) server that converts HTML content to Markdown format using Turndown.js.

Table of Contents

Features

Installation

npm install -g html-to-markdown-mcp

Or use with npx (no installation required):

Usage

With Claude Code

Add the server using the Claude CLI:

claude mcp add --transport stdio html-to-markdown -- npx html-to-markdown-mcp

Or if installed globally:

claude mcp add --transport stdio html-to-markdown -- html-to-markdown-mcp

With Claude Desktop

Add this server to your Claude Desktop configuration file:

Using npx (recommended):

{ "mcpServers": { "html-to-markdown": { "command": "npx", "args": ["html-to-markdown-mcp"] } } }

Or if installed globally:

{ "mcpServers": { "html-to-markdown": { "command": "html-to-markdown-mcp" } } }

With Cursor

Add this server to your Cursor MCP settings file:

Using npx (recommended):

{ "mcpServers": { "html-to-markdown": { "command": "npx", "args": ["html-to-markdown-mcp"] } } }

Or if installed globally:

{ "mcpServers": { "html-to-markdown": { "command": "html-to-markdown-mcp" } } }

Configuration methods:

  1. Via Cursor Settings (Recommended):
    • Open Cursor Settings: ⌘ + , (macOS) or Ctrl + , (Windows/Linux)
    • Navigate to File → Preferences → Cursor Settings
    • Select the MCP option
    • Add a new global MCP server with the configuration above
  2. Manual file editing:
    • Global: ~/.cursor/mcp.json (available across all projects)
    • Local: .cursor/mcp.json in your project directory (project-specific)

After adding the configuration, restart Cursor for the changes to take effect.

With Codex

Add this server to your Codex configuration using the CLI or by editing the config file:

Option 1: Using Codex CLI (Recommended):

codex mcp add html-to-markdown -- npx -y html-to-markdown-mcp

Or if installed globally:

codex mcp add html-to-markdown -- html-to-markdown-mcp

Option 2: Manual Configuration:

Edit ~/.codex/config.toml and add:

[mcp_servers.html-to-markdown] command = "npx" args = ["-y", "html-to-markdown-mcp"]

Or if installed globally:

[mcp_servers.html-to-markdown] command = "html-to-markdown-mcp"

The configuration file is located at ~/.codex/config.toml on all platforms (macOS, Linux, and Windows).

After updating the configuration, restart Codex or your Codex session for the changes to take effect.

Using Local Development Version

If you're developing or testing locally, you can add the MCP server directly from your local code:

With Claude Code:

claude mcp add --transport stdio html-to-markdown -- node /absolute/path/to/html-to-markdown-mcp/index.js

With Claude Desktop:

{ "mcpServers": { "html-to-markdown": { "command": "node", "args": ["/absolute/path/to/html-to-markdown-mcp/index.js"] } } }

Replace /absolute/path/to/html-to-markdown-mcp with the actual path to your cloned repository.

Available Tools

html_to_markdown

Fetch HTML from a URL or convert provided HTML content to Markdown format. This tool is automatically used by Claude whenever HTML needs to be fetched and converted.

Parameters:

Example 1: Fetch from URL (Recommended)

{ "url": "https://example.com" }

Example 2: Convert raw HTML

{ "html": "

Hello World

This is a test.

" }

Example 3: Fetch large page and save directly to file

{ "url": "https://www.docuseal.com/docs/api", "saveToFile": "./docuseal-api.md" }

Example 4: Limit returned content length

{ "url": "https://example.com", "maxLength": 5000 }

Output:

Example Domain

Source: https://example.com Saved: 2025-10-09T12:00:00.000Z

Example Domain

This domain is for use in illustrative examples...

save_markdown

Save markdown content to a file on disk. Use this to persist converted HTML or any markdown content.

Parameters:

Example:

{ "content": "# My Document\n\nThis is some markdown content.", "filePath": "./output/document.md" }

Usage: You can chain both tools together - first convert HTML to markdown, then save the result to a file.

When does it activate?

The MCP server will automatically be used by Claude when you:

Example prompts that trigger it:

Local Development

If you want to contribute or modify the server:

Clone the repository

git clone https://github.com/levz0r/html-to-markdown-mcp.git cd html-to-markdown-mcp

Install dependencies

npm install

Run the server

npm start

Testing

Run the test suite using Node's built-in test runner:

Run all tests

npm test

Run tests in watch mode (re-runs on file changes)

npm run test:watch

The test suite includes:

Publishing a New Version

The project uses automated CI/CD for publishing to npm:

  1. Update version using npm version scripts:
    npm run version:patch # 1.0.0 -> 1.0.1
    npm run version:minor # 1.0.0 -> 1.1.0
    npm run version:major # 1.0.0 -> 2.0.0
  2. Push the tag to trigger automated publishing:
    git push && git push --tags
  3. GitHub Actions will automatically:
    • Run all tests
    • Publish to npm if tests pass
    • Add provenance information to the package

Manual publishing (if needed):

npm run release:patch --otp= npm run release:minor --otp= npm run release:major --otp=

Technical Details

This server uses the same conversion approach as markdown-printer, a browser extension for saving web pages as Markdown files.

License

MIT