md-pdf-mcp

An MCP (Model Context Protocol) server that converts Markdown into beautifully branded PDFs with configurable themes. Supports GitHub-flavored Markdown tables, syntax-highlighted code blocks, blockquotes, images, and professional page layouts.

Features

• GFM Tables — Zebra-striped rows, colored headers, clean borders
• Syntax Highlighting — Powered by Shiki with 25+ languages
• Branded Theming — Configure fonts, colors, and logo via mcp.json
• Title Page — Optional cover page with logo and document title
• Table of Contents — Auto-generated from headings
• Header/Footer — Page numbers, custom text, configurable per-document
• Headless CI-ready — Deterministic PDF output via Playwright Chromium

Quick Start (Zero Install)

No npm install needed. Just add the server to your project's .mcp.json and npx handles the rest.

Add this to your project's .mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "md-pdf": {
      "command": "npx",
      "args": ["-y", "md-pdf-mcp"],
      "env": {}
    }
  },
  "mdPdf": {
    "fontFamily": "Inter, system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif",
    "primaryColor": "#1a1a2e",
    "secondaryColor": "#16213e",
    "accentColor": "#0f3460",
    "logoPath": "./assets/logo.png",
    "page": {
      "format": "Letter",
      "marginTop": "0.8in",
      "marginRight": "0.8in",
      "marginBottom": "0.9in",
      "marginLeft": "0.8in"
    },
    "header": { "enabled": true },
    "footer": { "enabled": true, "showPageNumbers": true }
  }
}

The mcpServers block registers the MCP server. The mdPdf block configures your brand theme. Both live in the same file. The -y flag auto-confirms the npx install so it runs without prompts.

Playwright's Chromium browser will be downloaded automatically on first run. If you need to install it manually:

npx playwright install chromium

Alternative: Global Install

If you prefer a permanent installation:

npm install -g md-pdf-mcp
npx playwright install chromium

Then reference it without -y in your .mcp.json:

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

MCP Client Configuration

Claude Code — Add to your project's .mcp.json (shown above) or to .claude/settings.json for global access.

Claude Desktop — Add to claude_desktop_config.json:

{
  "mcpServers": {
    "md-pdf": {
      "command": "npx",
      "args": ["-y", "md-pdf-mcp"],
      "env": {}
    }
  }
}

Place the mdPdf theme block in a mcp.json or .mcp.json file in your project root. The server searches for config in this order:

1. MD_PDF_CONFIG environment variable (explicit path)
2. mcp.json in the current working directory
3. .mcp.json in the current working directory
4. md-pdf.json or .md-pdf.json in the current working directory
5. Bundled defaults

3. Invoke the tool

The server exposes a single tool: markdown_to_pdf

From a file:

{
  "inputPath": "./docs/report.md",
  "outputPath": "./output/report.pdf",
  "title": "Q1 Status Report",
  "showToc": true,
  "headerText": "ACME Corp — Confidential",
  "footerText": "Generated with md-pdf-mcp"
}

From a raw string:

{
  "markdown": "# Hello World\n\nThis is a test.\n\n| A | B |\n|---|---|\n| 1 | 2 |",
  "outputPath": "./output/hello.pdf"
}

Theme Configuration

All theme values are read from the mdPdf block in your .mcp.json (or mcp.json) at runtime.

| Field | Type | Default | Description | |-------|------|---------|-------------| | fontFamily | string | "Inter, system-ui, ..." | CSS font stack | | primaryColor | hex | #1a1a2e | Headings, heading borders, table accent | | secondaryColor | hex | #16213e | Table header background, zebra striping | | accentColor | hex | #0f3460 | Links, blockquote borders, dividers | | logoPath | string | — | Path to logo image (relative to mcp.json) | | page.format | string | "Letter" | Page size ("Letter", "A4", etc.) | | page.margin* | string | "0.8in" | Page margins | | header.enabled | boolean | true | Show page header | | footer.enabled | boolean | true | Show page footer | | footer.showPageNumbers | boolean | true | Show page numbers in footer |

Colors must be valid hex (#RGB or #RRGGBB). If logoPath points to a missing file, the server warns and proceeds without a logo.

Tool Input Schema

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | inputPath | string | One of inputPath or markdown | Path to .md file | | markdown | string | One of inputPath or markdown | Raw Markdown content | | outputPath | string | Yes | Where to write the PDF | | title | string | No | If set, generates a title page | | showToc | boolean | No | Generate table of contents | | headerText | string | No | Text for page header | | footerText | string | No | Text for page footer (left side) |

Development

git clone https://github.com/justintabb/md-pdf-mcp.git
cd md-pdf-mcp
npm install
npx playwright install chromium
npm run build
npm test

License

MIT