markdown-pdf-converter

A powerful Model Context Protocol (MCP) server that converts Markdown files and content to beautifully styled PDFs with Mermaid diagrams and ApexCharts support. Built with MCP SDK 1.16.x featuring all transport modes: stdio, HTTP, and SSE.

✨ Features

🚀 Transport Layer Support (MCP SDK 1.16.x)

• stdio: Perfect for Claude Desktop integration
• Streamable HTTP: Modern web applications with session management
• SSE (Server-Sent Events): Legacy compatibility support
• CORS enabled: Browser-friendly with proper headers
• DNS rebinding protection: Enhanced security

📄 PDF Conversion

• 🔄 Two conversion modes: File-to-PDF and content-to-PDF
• 📊 Charts & diagrams: Mermaid diagrams + ApexCharts support
• 🎨 Modern styling: Professional typography with syntax highlighting
• 📄 Multiple formats: A4, A3, A5, Letter, Legal, Tabloid
• ⚙️ Configurable margins: Custom spacing in inches, mm, cm
• 📝 Front matter support: YAML metadata for document properties
• 🎯 Accessibility: Tagged PDFs with proper outline structure
• 📦 Large content support: JSON structure for handling 10,000+ line documents

🚀 Quick Start

Option 1: Use with npx (Recommended)

# Default stdio mode (for Claude Desktop)
npx markdown-pdf-mcp

# HTTP server mode
npx markdown-pdf-mcp http 3000

# SSE server mode (legacy)
npx markdown-pdf-mcp sse 3001

Option 2: Global Installation

npm install -g markdown-pdf-mcp

# Run in different modes
markdown-pdf-mcp              # stdio (default)
markdown-pdf-mcp http 3000    # HTTP server
markdown-pdf-mcp sse 3001     # SSE server

🔧 Integration Options

Claude Desktop (stdio)

Add to your Claude Desktop configuration:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

HTTP Server

# Start HTTP server on port 3000
npx markdown-pdf-mcp http 3000

# Or with npm
npm run start:http

SSE Server (Legacy)

# Start SSE server on port 3001
npx markdown-pdf-mcp sse 3001

# Or with npm
npm run start:sse

Restart Claude Desktop after configuration.

📖 Usage Examples

Convert Markdown File to PDF

"Convert my README.md file to PDF and save it as documentation.pdf"

Convert Markdown Content to PDF

"Take this markdown content and create a PDF with A4 format:
# My Document
This is **bold** text with a [link](https://example.com)
"

Large Content Support

"Convert this large markdown content to PDF: {content: 'Main content...', chunks: ['Section 1...', 'Section 2...']}"

Custom Formatting

"Convert the markdown file with custom margins of 1 inch on all sides and Letter format"

Charts & Diagrams

ApexCharts:

# Sales Data

```chart
{
  "chart": { "type": "line", "height": 350 },
  "series": [{ "name": "Sales", "data": [30, 40, 35, 50, 49, 60, 70] }],
  "xaxis": { "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"] }
}

**Mermaid:**
```markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

## 🚀 Transport Modes (MCP SDK 1.16.x)

This server implements **all transport modes** from the latest MCP SDK, making it compatible with various integration scenarios:

### 💻 stdio (Default) - Claude Desktop Ready
**Perfect for**: Claude Desktop, command-line tools, direct integrations
```bash
npx markdown-pdf-mcp

Features:

• Zero configuration required
• Direct stdin/stdout communication
• Ideal for desktop AI applications
• Automatic process lifecycle management

🌐 Streamable HTTP - Modern Web Applications

Perfect for: Web applications, microservices, cloud deployments

npx markdown-pdf-mcp http 3000

Features:

• Endpoints: POST/GET/DELETE /mcp
• Session management with mcp-session-id header
• CORS enabled for browser clients
• DNS rebinding protection for security
• Stateful sessions with automatic cleanup
• Error handling with proper HTTP status codes

Integration Example:

// Browser/Node.js client
const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId // Optional for new sessions
  },
  body: JSON.stringify(mcpRequest)
});

📡 SSE (Server-Sent Events) - Legacy Support

Perfect for: Backwards compatibility, existing SSE-based systems

npx markdown-pdf-mcp sse 3001

Features:

• SSE endpoint: GET /sse for real-time notifications
• Message endpoint: POST /messages for client requests
• Session-based communication
• Legacy compatibility with older MCP implementations

Integration Example:

// SSE connection for notifications
const eventSource = new EventSource('http://localhost:3001/sse');

// POST messages for requests
fetch('http://localhost:3001/messages?sessionId=abc123', {
  method: 'POST',
  body: JSON.stringify(mcpRequest)
});

🛠️ Available Tools

convert_markdown_to_pdf

Converts a markdown file to PDF (supports local files and URLs).

Parameters:

• markdownPath (string): Path to the markdown file (local path or URL)
• outputPath (string): Where to save the PDF
• format (optional): Page format (A4, A3, A5, Letter, Legal, Tabloid)
• margin (optional): Custom margins object

markdown_content_to_pdf

Converts markdown content directly to PDF (supports large content with JSON structure).

Parameters:

• markdownContent (string or object): Markdown content to convert (string or JSON object with content/chunks)
• outputPath (string): Where to save the PDF
• title (optional): Document title
• format (optional): Page format
• margin (optional): Custom margins object

🛠️ Installation & Deployment

Local Development

# Clone and install
git clone https://github.com/skmprb/markdown-pdf-converter.git
cd markdown-pdf-converter
npm install
npm run build

# Run in different modes
npm start              # stdio mode
npm run start:http     # HTTP server on port 3000
npm run start:sse      # SSE server on port 3001

Production Deployment

PM2 Process Manager

# Install globally
npm install -g markdown-pdf-mcp pm2

# Start with PM2
pm2 start "markdown-pdf-mcp http 3000" --name markdown-pdf-server
pm2 startup
pm2 save

🐛 Issues & Support

Found a bug or need help? Please open an issue on GitHub.

Built with ❤️ using MCP SDK 1.16.x