Skip to content
Back to search

mcp-pandoc

MCP server for document format conversion using pandoc.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vivekvells--mcp-pandoc/badge.svg)](/listings/vivekvells--mcp-pandoc)

HTML

<a href="/listings/vivekvells--mcp-pandoc"><img src="/api/listings/vivekvells--mcp-pandoc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing manually via claude_desktop_config.json config file

- On MacOS: `open ~/Library/Application\ Support/Claude/claude_desktop_config.json` - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

a) Only for local development & contribution to this repo

<details> <summary>Development/Unpublished Servers Configuration</summary>

ℹ️ Replace <DIRECTORY> with your locally cloned project path

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

</details>

b) Published Servers Configuration - Consumers should use this config

"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": [
      "mcp-pandoc"
    ]
  }
}
npx -y @smithery/cli install mcp-pandoc --client claude

- If you face any issue, use the "Published Servers Configuration" above directly instead of this cli.

**Note**: To use locally configured mcp-pandoc, follow "Development/Unpublished Servers Configuration" step above.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 435 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![Downloads](https://img.shields.io/pypi/dm/mcp-pandoc.svg)](https://pypi.python.org/pypi/mcp-pandoc)
  2. [![CI](https://github.com/vivekVells/mcp-pandoc/actions/workflows/ci.yml/badge.svg)](https://github.com/vivekVells/mcp-pandoc/actions/workflows/ci.yml)
  3. <br />
  4. ![image](https://github.com/user-attachments/assets/10f18317-58e7-430e-9aec-b706b60fe2c6)
  5. <!-- [![Downloads](https://static.pepy.tech/badge/mcp-pandoc/month)](https://pepy.tech/project/mcp-pandoc) -->
  6. <!-- ![PyPI - Downloads](https://img.shields.io/pypi/dm/mcp-pandoc?style=social) -->
  7. <!--
  8. [![Downloads](https://img.shields.io/pypi/dm/mcp-pandoc.svg)](https://pypi.python.org/pypi/mcp-pandoc)
  9. [![CI](https://github.com/vivekVells/mcp-pandoc/actions/workflows/ci.yml/badge.svg)](https://github.com/vivekVells/mcp-pandoc/actions/workflows/ci.yml)
  10. <a href="https://smithery.ai/server/mcp-pandoc"><img alt="Smithery Badge" src="https://smithery.ai/badge/mcp-pandoc"></a> <a href="https://glama.ai/mcp/servers/xyzzgaj9bk"><img width="380" height="200" src="https://glama.ai/mcp/servers/xyzzgaj9bk/badge" /></a>
  11. -->
  12. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/vivekvells-mcp-pandoc-badge.png)](https://mseep.ai/app/vivekvells-mcp-pandoc)
  13. <a href="https://glama.ai/mcp/servers/xyzzgaj9bk"><img width="380" height="200" src="https://glama.ai/mcp/servers/xyzzgaj9bk/badge" />
  14. # mcp-pandoc: A Document Conversion MCP Server
  15. > Officially included in the [Model Context Protocol servers](https://github.com/modelcontextprotocol/servers/blob/main/README.md) open-source project. 🎉
  16. ## Overview
  17. A Model Context Protocol server for document format conversion using [pandoc](https://pandoc.org/index.html). This server provides tools to transform content between different document formats while preserving formatting and structure.
  18. Please note that mcp-pandoc is currently in early development. PDF support is under development, and the functionality and available tools are subject to change and expansion as we continue to improve the server.
  19. Credit: This project uses the [Pandoc Python package](https://pypi.org/project/pandoc/) for document conversion, forming the foundation for this project.
  20. ## 📋 Quick Reference
  21. **New to mcp-pandoc?** Check out **[📖 CHEATSHEET.md](CHEATSHEET.md)** for
  22. - ⚡ Copy-paste examples for all formats
  23. - 🔄 Bidirectional conversion matrix
  24. - 🎯 Common workflows and pro tips
  25. - 🌟 Reference document styling guide
  26. _Perfect for quick lookups and getting started fast!_
  27. ## Demo
  28. [![mcp-pandoc - v1: Seamless Document Format Conversion for Claude using MCP server](https://img.youtube.com/vi/vN3VOb0rygM/maxresdefault.jpg)](https://youtu.be/vN3VOb0rygM)
  29. > 🎥 [Watch on YouTube](https://youtu.be/vN3VOb0rygM)
  30. <details>
  31. <summary>Screenshots</summary>
  32. <img width="2407" alt="Screenshot 2024-12-26 at 3 33 54 PM" src="https://github.com/user-attachments/assets/ce3f5396-252a-4bba-84aa-65b2a06b859e" />
  33. <img width="2052" alt="Screenshot 2024-12-26 at 3 38 24 PM" src="https://github.com/user-attachments/assets/8c525ad1-b184-41ca-b068-7dd34b60b85d" />
  34. <img width="1498" alt="Screenshot 2024-12-26 at 3 40 51 PM" src="https://github.com/user-attachments/assets/a1e0682d-fe44-40b6-9988-bf805627beeb" />
  35. <img width="760" alt="Screenshot 2024-12-26 at 3 41 20 PM" src="https://github.com/user-attachments/assets/1d7f5998-6d7f-48fa-adcf-fc37d0521213" />
  36. <img width="1493" alt="Screenshot 2024-12-26 at 3 50 27 PM" src="https://github.com/user-attachments/assets/97992c5d-8efc-40af-a4c3-94c51c392534" />
  37. </details>
  38. More to come...
  39. ## Tools
  40. 1. `convert-contents`
  41. - Transforms content between supported formats
  42. - Inputs:
  43. - `contents` (string): Source content to convert (required if input_file not provided)
  44. - `input_file` (string): Complete path to input file (required if contents not provided)
  45. - `input_format` (string): Source format of the content (defaults to markdown)
  46. - `output_format` (string): Target format (defaults to markdown)
  47. - `output_file` (string): Complete path for output file (required for pdf, docx, rst, latex, epub, odt, pptx formats)
  48. - `reference_doc` (string): Path to a reference document to use for styling (supported for docx, odt and pptx output; the file must match the output format)
  49. - `defaults_file` (string): Path to a Pandoc defaults file (YAML) containing conversion options
  50. - `filters` (array): List of Pandoc filter paths to apply during conversion
  51. - Supported formats, by direction:
  52. | Format | Read | Write |
  53. | -------- | :--: | :---: |
  54. | markdown | ✅ | ✅ |
  55. | html | ✅ | ✅ |
  56. | docx | ✅ | ✅ |
  57. | odt | ✅ | ✅ |
  58. | rst | ✅ | ✅ |
  59. | latex | ✅ | ✅ |
  60. | epub | ✅ | ✅ |
  61. | ipynb | ✅ | ✅ |
  62. | txt | ✅ | ✅ |
  63. | **pdf** | ❌ | ✅ |
  64. | **pptx** | ❌ | ✅ |
  65. - Note: For advanced formats (pdf, docx, rst, latex, epub, odt, pptx), an output_file path is required
  66. ### 🔧 Advanced Features
  67. #### Defaults Files (YAML Configuration)
  68. Use defaults files to create reusable conversion templates with consistent formatting:
  69. ```yaml
  70. # academic-paper.yaml
  71. from: markdown
  72. to: pdf
  73. number-sections: true
  74. toc: true
  75. metadata:
  76. title: "Academic Paper"
  77. author: "Research Team"
  78. ```
  79. Example usage: `"Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf"`
  80. #### Pandoc Filters
  81. Apply custom filters for enhanced processing:
  82. Example usage: `"Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as docs.html"`
  83. > 💡 **For comprehensive examples and workflows**, see **[CHEATSHEET.md](CHEATSHEET.md)**
  84. ## 📊 Supported Formats & Conversions
  85. ### Bidirectional Conversion Matrix
  86. Rows are source formats, columns are targets. PDF and PPTX have no rows because pandoc cannot read them.
  87. | From\To | MD | HTML | TXT | DOCX | ODT | RST | LaTeX | EPUB | IPYNB | PDF | PPTX |
  88. | ------------ | --- | ---- | --- | ---- | --- | --- | ----- | ---- | ----- | --- | ---- |
  89. | **Markdown** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  90. | **HTML** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  91. | **TXT** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  92. | **DOCX** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  93. | **ODT** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  94. | **RST** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  95. | **LaTeX** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  96. | **EPUB** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  97. | **IPYNB** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
  98. ### A Note on Write-Only Formats
  99. **PDF** and **PPTX** can be produced but not read.
  100. Pandoc has never shipped a PDF reader. Pandoc gained a PowerPoint reader in 3.8.3 (released 2025-12-01), but this project declares no minimum pandoc version, and Ubuntu 24.04 still ships pandoc 3.1.3, so `pptx` input is not offered. Tracked in [#54](https://github.com/vivekVells/mcp-pandoc/issues/54) and [#49](https://github.com/vivekVells/mcp-pandoc/issues/49).
  101. PPTX **output** needs no particular pandoc version. The PowerPoint writer has existed since pandoc 2.0.5.
  102. ### Format Categories
  103. | Category | Formats | Requirements |
  104. | ------------ | ---------------------------------- | ------------------------------- |
  105. | **Basic** | MD, HTML, TXT, IPYNB | None, returned inline |
  106. | **Advanced** | DOCX, ODT, PDF, PPTX, RST, LaTeX, EPUB | Must specify `output_file` path |
  107. | **Styled** | DOCX, ODT, PPTX with reference doc | Custom template support ⭐ |
  108. ### Requirements by Format
  109. - **PDF (.pdf)** - requires TeX Live installation
  110. - **DOCX (.docx), ODT (.odt), PPTX (.pptx)** - support custom styling via reference documents, and the reference must be the same format as the output
  111. - **All others** - no additional requirements
  112. Note: For advanced formats:
  113. 1. Complete file paths with filename and extension are required
  114. 2. **PDF conversion requires TeX Live installation** (see Critical Requirements section -> For macOS: `brew install texlive`)
  115. 3. When no output path is specified:
  116. - Basic formats: Displays converted content in the chat
  117. - Advanced formats: May save in system temp directory (/tmp/ on Unix systems)
  118. ## Usage & configuration
  119. **NOTE: Ensure to complete installing required packages mentioned below under "Critical Requirements".**
  120. To use the published one
  121. ```bash
  122. {
  123. "mcpServers": {
  124. "mcp-pandoc": {
  125. "command": "uvx",
  126. "args": ["mcp-pandoc"]
  127. }
  128. }
  129. }
  130. ```
  131. **💡 Quick Start**: See **[CHEATSHEET.md](CHEATSHEET.md)** for copy-paste examples and common workflows.
  132. ### ⚠️ Important Notes
  133. #### Critical Requirements
  134. 1. **Pandoc Installation**
  135. - **Required**: Install `pandoc` - the core document conversion engine
  136. - Installation:
  137. ```bash
  138. # macOS
  139. brew install pandoc
  140. # Ubuntu/Debian
  141. sudo apt-get install pandoc
  142. # Windows
  143. # Download installer from: https://pandoc.org/installing.html
  144. ```
  145. - **Verify**: `pandoc --version`
  146. 2. **UV package installation**
  147. - **Required**: Install `uv` package (includes `uvx` command)
  148. - Installation:
  149. ```bash
  150. # macOS
  151. brew install uv
  152. # Windows/Linux
  153. pip install uv
  154. ```
  155. - **Verify**: `uvx --version`
  156. 3. **PDF Conversion Prerequisites:** Only needed if you need to convert & save pdf
  157. - TeX Live must be installed before attempting PDF conversion
  158. - Installation commands:
  159. ```bash
  160. # Ubuntu/Debian
  161. sudo apt-get install texlive-xetex
  162. # macOS
  163. brew install texlive
  164. # Windows
  165. # Install MiKTeX or TeX Live from:
  166. # https://miktex.org/ or https://tug.org/texlive/
  167. ```
  168. 4. **File Path Requirements**
  169. - When saving or converting files, you MUST provide complete file paths including filename and extension
  170. - The tool does not automatically generate filenames or extensions
  171. #### Examples
  172. ✅ Correct Usage:
  173. ```bash
  174. # Converting content to PDF
  175. "Convert this text to PDF and save as /path/to/document.pdf"
  176. # Converting between file formats
  177. "Convert /path/to/input.md to PDF and save as /path/to/output.pdf"
  178. # Converting to DOCX with a reference document template
  179. "Convert input.md to DOCX using template.docx as reference and save as output.docx"
  180. # Converting to ODT with a reference document template
  181. "Convert input.md to ODT using template.odt as reference and save as output.odt"
  182. # Converting to a branded PowerPoint deck
  183. "Convert slides.md to PPTX using template.pptx as reference and save as deck.pptx"
  184. # Step-by-step reference document workflow
  185. "First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" or if you already have one, use that
  186. "Then convert with custom styling: Convert this text to DOCX using /path/to/custom-reference.docx as reference and save as /path/to/styled-output.docx"
  187. ```
  188. ❌ Incorrect Usage:
  189. ```bash
  190. # Missing filename and extension
  191. "Save this as PDF in /documents/"
  192. # Missing complete path
  193. "Convert this to PDF"
  194. # Missing extension
  195. "Save as /documents/story"
  196. ```
  197. #### Common Issues and Solutions
  198. 1. **PDF Conversion Fails**
  199. - Error: "xelatex not found"
  200. - Solution: Install TeX Live first (see installation commands above)
  201. 2. **File Conversion Fails**
  202. - Error: "Invalid file path"
  203. - Solution: Provide complete path including filename and extension
  204. - Example: `/path/to/document.pdf` instead of just `/path/to/`
  205. 3. **Format Conversion Fails**
  206. - Error: "Unsupported format"
  207. - Solution: Use only supported formats:
  208. - Basic: txt, html, markdown
  209. - Advanced: pdf, docx, rst, latex, epub
  210. 4. **Reference Document Issues**
  211. - Error: "Reference document not found"
  212. - Solution: Ensure the reference document path exists and is accessible
  213. - Error: "reference_doc must be a '.odt' file when output_format is 'odt'"
  214. - Solution: The reference document must be the same format as the output. Pandoc does not check this itself: a mismatched reference is silently ignored for DOCX output, and produces an ODT file that cannot be opened
  215. - Note: Reference documents work with DOCX, ODT and PPTX output formats
  216. - How to create: `pandoc -o reference.docx --print-default-data-file reference.docx`, and likewise with `reference.odt` or `reference.pptx`
  217. ## Quickstart
  218. <!-- Uncomment after smithery fix
  219. ### Install
  220. #### Option 1: Installing manually via claude_desktop_config.json config file
  221. -->
  222. ### Installing manually via claude_desktop_config.json config file
  223. - On MacOS: `open ~/Library/Application\ Support/Claude/claude_desktop_config.json`
  224. - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  225. a) Only for local development & contribution to this repo
  226. <details>
  227. <summary>Development/Unpublished Servers Configuration</summary>
  228. ℹ️ Replace <DIRECTORY> with your locally cloned project path
  229. ```bash
  230. "mcpServers": {
  231. "mcp-pandoc": {
  232. "command": "uv",
  233. "args": [
  234. "--directory",
  235. "<DIRECTORY>/mcp-pandoc",
  236. "run",
  237. "mcp-pandoc"
  238. ]
  239. }
  240. }
  241. ```
  242. </details>
  243. b) Published Servers Configuration - Consumers should use this config
  244. ```bash
  245. "mcpServers": {
  246. "mcp-pandoc": {
  247. "command": "uvx",
  248. "args": [
  249. "mcp-pandoc"
  250. ]
  251. }
  252. }
  253. ```
  254. <!-- Uncomment after smithery cli fix
  255. #### Option 2: To install Published Servers Configuration automatically via Smithery
  256. Run the following bash command to install **published** [mcp-pandoc pypi](https://pypi.org/project/mcp-pandoc) for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-pandoc):
  257. ```bash
  258. npx -y @smithery/cli install mcp-pandoc --client claude
  259. ```
  260. -->
  261. - If you face any issue, use the "Published Servers Configuration" above directly instead of this cli.
  262. **Note**: To use locally configured mcp-pandoc, follow "Development/Unpublished Servers Configuration" step above.
  263. ## Development
  264. ### Testing
  265. To run the comprehensive test suite and validate all supported bidirectional conversions, use the following command:
  266. ```bash
  267. uv run pytest tests/test_conversions.py
  268. ```
  269. This ensures backward compatibility and verifies the tool's core functionality.
  270. ### Building and Publishing
  271. To prepare the package for distribution:
  272. 1. Sync dependencies and update lockfile:
  273. ```bash
  274. uv sync
  275. ```
  276. 2. Build package distributions:
  277. ```bash
  278. uv build
  279. ```
  280. This will create source and wheel distributions in the `dist/` directory.
  281. 3. Publish to PyPI:
  282. ```bash
  283. uv publish
  284. ```
  285. Note: You'll need to set PyPI credentials via environment variables or command flags:
  286. - Token: `--token` or `UV_PUBLISH_TOKEN`
  287. - Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
  288. ### Debugging
  289. Since MCP servers run over stdio, debugging can be challenging. For the best debugging
  290. experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
  291. You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
  292. ```bash
  293. npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc
  294. ```
  295. Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
  296. ---
  297. ## Contributing
  298. We welcome contributions to enhance mcp-pandoc! Here's how you can get involved:
  299. 1. **Report Issues**: Found a bug or have a feature request? Open an issue on our [GitHub Issues](https://github.com/vivekVells/mcp-pandoc/issues) page.
  300. 2. **Submit Pull Requests**: Improve the codebase or add features by creating a pull request.
  301. ---

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.