markdown-new-mcp

MCP (Model Context Protocol) server for markdown.new file conversion API. Convert PDF, DOCX, XLSX, images and 20+ formats to Markdown.

Installation

npm install markdown-new-mcp

Usage

With Claude Desktop or Claude Code

For stdio MCP clients, use npx -y so the server starts under Node.js and preserves the JSON-RPC stdio stream. Add this to your Claude config:

{
  "mcpServers": {
    "markdown-new": {
      "command": "npx",
      "args": ["-y", "markdown-new-mcp@latest"]
    }
  }
}

With opencode

Add this to the mcp section of ~/.config/opencode/opencode.json:

{
  "mcp": {
    "markdown-new": {
      "type": "local",
      "command": ["npx", "-y", "markdown-new-mcp@latest"]
    }
  }
}

With API Key (Optional)

For higher rate limits, you can provide an API key via environment variable:

{
  "mcpServers": {
    "markdown-new": {
      "command": "npx",
      "args": ["-y", "markdown-new-mcp@latest"],
      "env": {
        "MARKDOWN_NEW_API_KEY": "mk_your_api_key_here"
      }
    }
  }
}

Optional:

• MARKDOWN_NEW_TIMEOUT_MS: request timeout in milliseconds for upstream API calls (default: 30000)

Available Tools

convert_url_to_markdown

Extract clean Markdown from a remote file URL. Use this for PDF, DOCX, XLSX, CSV, HTML, images and other supported file URLs when the user needs readable Markdown.

Parameters:

• url (string, required): HTTP or HTTPS URL of the remote file
• api_key (string, optional): API key for higher rate limits; the server also reads MARKDOWN_NEW_API_KEY

Example:

Convert this PDF to markdown: https://example.com/document.pdf

convert_file_to_markdown

Extract clean Markdown from a local file path visible to the MCP server process. Use this when the user provides an absolute path on the same machine running the server.

Parameters:

• file_path (string, required): The absolute path to the local file
• api_key (string, optional): API key for higher rate limits; the server also reads MARKDOWN_NEW_API_KEY

Example:

Convert /path/to/document.pdf to markdown

convert_url_to_json

Return the full structured markdown.new response for a remote file URL, including extracted content plus metadata such as title, tokens and duration when provided by the API.

Parameters:

• url (string, required): The URL of the remote file
• api_key (string, optional): API key for higher rate limits; the server also reads MARKDOWN_NEW_API_KEY

Supported Formats

• Documents: PDF, DOCX, ODT
• Spreadsheets: XLSX, XLS, XLSM, XLSB, ET, ODS, Numbers
• Images: JPG, JPEG, PNG, WebP, SVG
• Text/Data: TXT, MD, CSV, JSON, XML, HTML, HTM

Limits

• Without API Key: 500 requests/day per IP
• With API Key: Higher limits available
• Maximum File Size: 10MB

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run dev

# Smoke test the stdio MCP server
npm run build
npm run smoke:stdio -- node dist/index.js

License

MIT