Markdown to Text MCP Server

A powerful Model Context Protocol (MCP) server that converts Markdown documents to plain text. Supports both stdio and HTTP transport protocols for use as local tools or remote services.

Features

• 📝 Complete Markdown Support: Handles all common elements including headers, lists, links, images, code blocks, tables, etc.
• 🎛️ Flexible Conversion Options: Multiple output formats and style configurations
• 🔧 Dual Protocol Support: stdio mode (Claude Desktop) and HTTP mode (remote clients)
• 📁 Batch Processing: Directory scanning and bulk file conversion
• 🌐 URL Support: Direct processing of remote Markdown files
• 🔒 Security Hardened: Comprehensive input validation and security protection
• ⚡ High Performance: Optimized conversion engine with concurrency control

Quick Start

Installation

Option 1: Clone and Build

git clone <repository-url>
cd md_to_text_mcp
npm install
npm run build

Option 2: Use with npx (Recommended)

# From npm registry (if published)
npx md_to_text_mcp --help

# From GitHub repository  
npx https://github.com/MD-TO-TEXT/md_to_text --help

# Local development
npm pack
npx ./md_to_text_mcp-1.0.0.tgz --help

Basic Usage

# Stdio mode (default)
npm start
# or with npx
npx md_to_text_mcp

# HTTP mode
npm run dev:http
# or with npx  
npx md_to_text_mcp --mode http --port 3000

Using with npx

npx allows you to run the tool without installing it globally. Here's how to use it:

Quick Test

# Test the tool help
npx md_to_text_mcp --help

# Run in stdio mode for Claude Desktop
npx md_to_text_mcp --mode stdio

# Start HTTP server
npx md_to_text_mcp --mode http --port 3000

# Custom configuration
npx md_to_text_mcp --mode http --host 0.0.0.0 --port 8080 --cors

From Local Package

If you're developing locally:

# Create package
npm run build
npm pack

# Run with npx
npx ./md_to_text_mcp-1.0.0.tgz --help
npx ./md_to_text_mcp-1.0.0.tgz --mode stdio

Integration with Claude Desktop via npx

You can configure Claude Desktop to use the tool via npx:

{
  "mcpServers": {
    "md-to-text": {
      "command": "npx",
      "args": ["md_to_text_mcp", "--mode", "stdio"],
      "cwd": "/tmp"
    }
  }
}

Note: Using npx in Claude Desktop config requires that the package is published to npm registry or available in a git repository.

Tools

convert_text - Text Conversion

Convert Markdown text directly to plain text.

convert_file - File Conversion

Read and convert local Markdown files.

convert_url - URL Conversion

Fetch and convert remote Markdown content from URLs.

batch_convert - Batch Conversion

Batch process Markdown files in directories.

Conversion Options

• preserveLinks: Preserve link URLs
• listStyle: List style (bullets/numbers/none)
• codeHandling: Code handling (preserve/remove/inline)
• tableFormat: Table format (simple/grid/none)
• headingStyle: Heading style (hash/underline/none)

Claude Desktop Integration

Add to Claude for Desktop configuration file:

{
  "mcpServers": {
    "md-to-text": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/md_to_text_mcp"
    }
  }
}

Command Line Options

md-to-text-mcp [OPTIONS]

OPTIONS:
  --mode <mode>         Server mode: 'stdio' or 'http' (default: stdio)
  --port <port>         HTTP server port (default: 3000)
  --host <host>         HTTP server host (default: localhost)
  --cors                Enable CORS for HTTP mode
  --no-cors             Disable CORS for HTTP mode
  --help, -h            Show help message

EXAMPLES:
  md-to-text-mcp                              # stdio mode
  md-to-text-mcp --mode http --port 3000      # HTTP mode
  md-to-text-mcp --mode http --host 0.0.0.0   # Allow external access

Environment Variables

Variable	Description	Default
MCP_MODE	Server mode (stdio/http)	stdio
MCP_PORT	HTTP server port	3000
MCP_HOST	HTTP server host	localhost
MAX_FILE_SIZE	Max file size (bytes)	10485760 (10MB)
URL_TIMEOUT	URL request timeout (ms)	30000 (30s)
ALLOWED_EXTENSIONS	Allowed file extensions	.md,.markdown,.txt

Docker Support

# Build image
docker build -t md-to-text-mcp .

# Run HTTP mode
docker run -p 3000:3000 md-to-text-mcp

# Health check
curl http://localhost:3000/health

API Examples

Text Conversion

{
  "name": "convert_text",
  "arguments": {
    "markdown": "# Hello World\n\nThis is **bold** text.",
    "options": {
      "preserveLinks": true,
      "listStyle": "bullets"
    }
  }
}

File Conversion

{
  "name": "convert_file",
  "arguments": {
    "path": "/path/to/document.md",
    "options": {
      "headingStyle": "underline"
    }
  }
}

URL Conversion

{
  "name": "convert_url",
  "arguments": {
    "url": "https://raw.githubusercontent.com/user/repo/main/README.md",
    "options": {
      "codeHandling": "remove"
    }
  }
}

Batch Conversion

{
  "name": "batch_convert",
  "arguments": {
    "directory": "/path/to/docs",
    "recursive": true,
    "options": {
      "tableFormat": "simple"
    }
  }
}

Security

The server includes multiple layers of security:

• Path Traversal Protection: Prevents access to system directories
• File Size Limits: Default 10MB maximum
• URL Validation: Only allows HTTP/HTTPS protocols
• Private IP Filtering: Blocks access to internal networks
• Content Sanitization: Removes potentially malicious content
• Request Timeouts: Prevents long-running operations

Development

Project Structure

src/
├── engine/          # Conversion engine
├── security/        # Security validation
├── tools/           # MCP tool implementations
├── transports/      # Transport protocols
├── types/           # TypeScript type definitions
└── index.ts         # Main entry point

Development Commands

npm run build        # Build project
npm run watch        # Watch mode build
npm run dev:stdio    # Development - stdio
npm run dev:http     # Development - HTTP

Related Resources

Markdown Documentation

• Complete Markdown Guide - Comprehensive Markdown syntax tutorial for efficient md to text conversion

Online Tools

• MD to Text Converter - Free online Markdown to text conversion tool with real-time processing

License

MIT License