Markdown to PDF MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to convert Markdown files and content to beautifully formatted PDF documents. Built with Node.js and Playwright for high-quality, browser-based PDF generation.

What is This?

This MCP server adds PDF conversion capabilities to Claude Desktop and other MCP-compatible AI assistants. Simply ask Claude to "convert my markdown file to PDF" and it handles the conversion using this server.

Features

• 🎨 Beautiful Defaults: GitHub-style markdown rendering out of the box
• 🎯 Custom Styling: Full control with custom CSS
• 📄 Multiple Formats: Support for A4, Letter, Legal, and more
• 🔄 Flexible Input: Convert from files or direct markdown content
• 🖨️ Print Options: Landscape/portrait, margins, background graphics
• ⚡ Fast: Powered by Playwright's Chromium engine

Installation

You can use this MCP server in two ways:

Option 1: Use Directly from GitHub (Recommended)

No cloning required! Use npx to run directly from the GitHub repository.

Configuration

Edit your Claude Desktop config file:

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

{
  "mcpServers": {
    "pdf-generator": {
      "command": "npx",
      "args": ["-y", "github:warrenandre/MCP_MD_TO_PDF"]
    }
  }
}

That's it! The first time you use it, npx will automatically download and set up the server. Future uses will be faster as it caches the installation.

Benefits:

• No local installation needed
• Always uses the latest version from GitHub
• Minimal setup
• Works on any machine with Node.js

---

Option 2: Run Locally (For Development/Customization)

If you want to modify the server or run it locally:

Step 1: Clone the Repository

git clone https://github.com/warrenandre/MCP_MD_TO_PDF.git
cd MCP_MD_TO_PDF

Step 2: Install Dependencies

npm install

Step 3: Install Playwright

Playwright needs to download Chromium (first time only):

npx playwright install chromium

Step 4: Configure Claude Desktop

Edit your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "MD_TO_PDF": {
      "command": "node",
      "args": ["C:\\path\\to\\MCP_MD_TO_PDF\\index.js"]
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "MD_TO_PDF": {
      "command": "node",
      "args": ["/path/to/MCP_MD_TO_PDF/index.js"]
    }
  }
}

Important: Replace the path with the actual absolute path to your index.js file.

---

Final Step (Both Options)

Restart Claude Desktop for the configuration to take effect.

Test it: Open Claude and try:

Convert sample.md to output.pdf

How to Use

Once configured, simply ask Claude to convert markdown to PDF using natural language:

Basic Conversion

Convert document.md to document.pdf

Custom Page Format

Convert report.md to report.pdf using Letter format in landscape mode

With Custom CSS

Convert notes.md to styled-notes.pdf with custom CSS:
body { font-family: Georgia, serif; font-size: 14pt; }
h1 { color: #2c3e50; }

Direct Content Conversion

Create a PDF from this markdown content: 
# Meeting Notes
- Item 1
- Item 2

Save as meeting.pdf

Get Default Styling

Show me the default CSS for PDF generation

MCP Tools Reference

This server provides three tools that Claude can use:

1. convert_markdown_to_pdf

Convert a Markdown file to PDF.

Parameters:

• markdownPath (required): Path to input .md file
• outputPath (required): Path where PDF will be saved
• customCss (optional): Custom CSS styling
• format (optional): Paper format - 'A4', 'Letter', 'Legal', 'A3', 'A5', 'Tabloid' (default: 'A4')
• landscape (optional): Use landscape orientation (default: false)
• printBackground (optional): Print background graphics (default: true)

Example request:

Convert README.md to documentation.pdf

2. convert_markdown_content_to_pdf

Convert markdown content directly to PDF without reading from a file.

Parameters:

• markdownContent (required): Markdown text to convert
• outputPath (required): Path where PDF will be saved
• customCss (optional): Custom CSS styling
• format (optional): Paper format (default: 'A4')
• landscape (optional): Use landscape orientation (default: false)
• printBackground (optional): Print background graphics (default: true)

Example request:

Convert this markdown to PDF: # Hello World\n\nThis is a **test**.
Save it as output.pdf

3. get_default_css

Get the default CSS template used for styling.

Use this to:

• See the default styling
• Use as a starting point for customization
• Understand available CSS classes

Example request:

Show me the default CSS for PDF generation

Default CSS Styling

The server includes GitHub-style markdown CSS by default with:

• Clean typography with system fonts
• Syntax highlighting for code blocks
• Styled tables, blockquotes, and lists
• Responsive images
• Professional headings with borders

Use get_default_css tool to see the complete default stylesheet.

PDF Options

Paper Formats

• A4: 210mm × 297mm (default)
• Letter: 8.5in × 11in
• Legal: 8.5in × 14in
• A3: 297mm × 420mm
• A5: 148mm × 210mm
• Tabloid: 11in × 17in

Margins

Default margins: 1cm on all sides

Custom margins in customCss:

@page {
  margin: 2cm 1.5cm;
}

Troubleshooting

Server Not Showing Up in Claude

For GitHub Installation (Option 1):

1. Ensure Node.js is installed (node --version)
2. Check the config file syntax is correct (valid JSON)
3. Restart Claude Desktop completely
4. Check Claude logs for errors (see locations below)

For Local Installation (Option 2):

1. Verify the path in config is correct and absolute
2. Ensure index.js exists at that location
3. Restart Claude Desktop completely
4. Check Claude logs for startup errors

Claude Log Locations:

• Windows: %APPDATA%\Claude\logs\
• macOS: ~/Library/Logs/Claude/

Playwright Not Installed

Error: "Executable doesn't exist at ..."

Solution:

npx playwright install chromium

This typically only affects local installations (Option 2), as GitHub installation handles dependencies automatically.

File Not Found Errors

Error: "ENOENT: no such file or directory"

Solutions:

• Use absolute paths (e.g., C:\Users\...\file.md)
• Ensure the file exists and has read permissions
• Check the file extension is .md

PDF Looks Different Than Expected

Solutions:

• Ask Claude to show the default CSS: Show me the default CSS
• Test with custom CSS to override defaults
• Enable printBackground: true for colors and backgrounds
• Try different paper formats (Letter, A4, etc.)

Permission Denied

Error: "EACCES: permission denied"

Solutions:

• Ensure the output directory exists and is writable
• Check file permissions on the output path
• Try saving to a different location (e.g., Desktop)

Technical Details

Architecture

This is a Model Context Protocol (MCP) server that:

1. Registers tools that AI assistants can discover and use
2. Communicates via stdio (standard input/output)
3. Receives tool invocation requests in JSON format
4. Executes the requested PDF conversion
5. Returns results back to the AI assistant

Technology Stack

• Node.js (ES Modules) - Runtime environment
• @modelcontextprotocol/sdk - MCP protocol implementation
• Playwright (Chromium) - Headless browser for PDF generation
• Marked - Markdown to HTML parser

Conversion Process

1. Parse: Markdown → HTML (via Marked library)
2. Style: Apply CSS (default or custom)
3. Render: Load HTML in headless Chromium (via Playwright)
4. Generate: Export rendered page to PDF with specified options

Why Playwright?

Playwright provides:

• True browser rendering (same as Chrome)
• Full CSS support including print media queries
• High-quality PDF generation
• Support for complex layouts, fonts, and graphics

Learn more about MCP: modelcontextprotocol.io

Development

Running Locally for Testing

If you've cloned the repository (Option 2):

node index.js

The server will start and communicate via stdio. You can test it with your MCP client.

Testing with Claude

1. Create a test markdown file:

   echo "# Test Document\n\nThis is a **test**." > test.md
   

2. Ask Claude:

   Convert test.md to test.pdf
   

3. Check the output PDF in your working directory.

Modifying the Server

• Change default CSS: Edit the DEFAULT_CSS constant in index.js
• Add new tools: Add to the tools array in ListToolsRequestSchema handler
• Customize PDF options: Modify the htmlToPdf function
• Update dependencies: Run npm update

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests on GitHub.

License

MIT

Links

• GitHub Repository: https://github.com/warrenandre/MCP_MD_TO_PDF
• Model Context Protocol: https://modelcontextprotocol.io
• Playwright: https://playwright.dev
• Marked: https://marked.js.org

---

Questions or Issues? Please open an issue on GitHub.