# mcp-pandoc: exposing pandoc document conversion as an MCP server tool

> mcp-pandoc wraps pandoc in a Model Context Protocol server so an assistant can convert documents between formats, apply YAML defaults files, and run pandoc filters. It is a thin, well-scoped adapter, and the README is upfront that it is early software with PDF support still in progress.

**vivekVells/mcp-pandoc** — MCP server for document format conversion using pandoc.

- Repository: https://github.com/vivekVells/mcp-pandoc
- Website: https://pypi.org/project/mcp-pandoc
- Stars: 583 · Forks: 63
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/vivekvells-mcp-pandoc

## One tool, convert-contents, with a deliberately narrow input surface

mcp-pandoc is a Model Context Protocol server for document format conversion using pandoc, providing tools to transform content between different document formats while preserving formatting and structure. There is one tool in the list, and it is `convert-contents`. Its inputs are declared explicitly: `contents` as the source content to convert, required if `input_file` is not provided; `input_file` as a complete path to an input file, required if contents is not; `input_format` and `output_format`, both defaulting to markdown; `output_file` as a complete path for the output, required for the pdf, docx, rst, latex, epub, odt and pptx formats; `reference_doc` for styling, supported for docx, odt and pptx output where the file must match the output format; `defaults_file` for a Pandoc defaults file in YAML; and `filters`, an array of pandoc filter paths to apply during the conversion. The audience is whoever configures an MCP client, and the design goal is that the assistant can call one well-described tool instead of composing shell commands.

## PDF and PPTX can be written but not read

The format table is the most useful part of the README, because it tells you exactly what an assistant can and cannot do. Markdown, HTML, docx, odt, rst, latex, epub, ipynb and txt are all readable and writable. PDF and PPTX are write only, and the README gives the reason with unusual precision. 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. The consequence for anyone wiring this into an assistant is concrete. You can hand a model a Markdown file and ask for a PDF, and you can hand it a docx and ask for Markdown, but asking it to read a PDF and summarise it will not work through this server, because the request never reaches a pandoc reader. The issue is tracked in the repository.

## Defaults files are where the reusable configuration lives

The advanced features section is short and practical. Defaults files are described as a way to create reusable conversion templates with consistent formatting, and the example is a YAML file:

```yaml
# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "Academic Paper"
  author: "Research Team"
```

The example usage in the README is a natural language instruction, converting a paper to PDF using the named defaults file and saving the result. That is the point of the whole design. Because the server speaks MCP, the arguments arrive as tool parameters, so a defaults file is the natural place to keep the parts of a conversion that repeat. The alternative is embedding every option in the prompt every time, which is exactly the pattern the tool is meant to remove. Pandoc filters work the same way, with the example applying a filter path to a Markdown to HTML conversion, and a Mermaid filter is the kind of thing that filter list exists for.

## The Python side is a thin layer over the pandoc package

The project credits the Pandoc Python package as the foundation for the document conversion. The dependencies in `pyproject.toml` show the stack in full: `mcp>=2,<3` for the protocol implementation, `jsonschema>=4.25.1` for validating the tool schema, `pyyaml>=6.0.2`, `pandoc>=2.4`, `pypandoc>=1.14`, `pandocfilters>=1.5.0`, and `panflute>=2.3.1`. The `pandoc`, `pypandoc`, `pandocfilters` and `panflute` combination is a well-known way of driving pandoc from Python, and `jsonschema` alongside `mcp` is what lets the server declare and validate the tool contract. The project metadata describes itself as MCP to interface with pandoc to convert files to different formats with enhanced features like Mermaid diagram conversion and defaults file support. The package requires Python 3.11 or newer, builds with hatchling, and exposes a console entry point named `mcp-pandoc` bound to `mcp_pandoc:main`.

## The Docker image carries a LaTeX toolchain for the PDF path

The Dockerfile in the repository is generated by smithery.ai and shows what a container deployment costs. The base image is `python:3.11-slim-bookworm`, the work happens in `/app`, and the system dependencies installed are `texlive-xetex` and `pandoc`:

```dockerfile
RUN apt-get update && \
    apt-get install -y texlive-xetex pandoc && \
    rm -rf /var/lib/apt/lists/*
```

That `texlive-xetex` line is the whole story of the PDF path. Producing a PDF from Markdown through pandoc means running LaTeX, and LaTeX means a TeX distribution, so a container that has to emit PDFs is carrying a large system dependency. The rest of the image is conventional: copy the application files, install the Python dependencies with `pip install --no-cache-dir .`, set `UV_COMPILE_BYTECODE=1` and `UV_LINK_MODE=copy`, and start the server with an entrypoint of `uv run mcp-pandoc`. The repository also ships a `smithery.yaml`, which is the configuration format for that deployment path, plus a `demo/` directory with screenshots of the conversion tool in use.

## The README points at a cheatsheet rather than repeating the matrix

The Quick Reference section of the README is a pointer, not the content. It sends new users to CHEATSHEET.md in the repository for copy-paste examples for all formats, a bidirectional conversion matrix, common workflows and pro tips, and a reference document styling guide. That is a reasonable choice for a tool whose capability surface is a moving matrix, and the repository root confirms the file is there. The rest of the documentation structure supports the same idea. There are `docs/` and `examples/` directories, an `AGENTS.md` and a `CLAUDE.md` at the root, and a `MCP_LOCAL_VALIDATION.md` file that suggests local validation of the server is a documented practice. The dev tooling is modern as well, with a `dependency-groups` block rather than an extras section, listing pytest, pytest-asyncio, ruff, yamllint and pre-commit, and a ruff configuration that selects a broad rule set including `D` for docstrings and `S` for security checks.

## Early development, and the release notes say what is still moving

The README states plainly that mcp-pandoc is currently in early development, that PDF support is under development, and that the functionality and available tools are subject to change and expansion. The release history matches that description. v0.10.0 on 2026-08-10 was Reference document styling for ODT, v0.11.0 followed the same day, and v0.11.1 on 2026-08-15 was Cross-platform CI reliability, with the last push on 2026-08-15. The version numbers say the same thing, since the project is at 0.11.1 and pre-1.0 versions in Python carry no compatibility promise. The project is included in the Model Context Protocol servers open-source project, and the PyPI page is the project home. The practical reading for an adopter is that the tool surface, in particular the set of formats and the schema of `convert-contents`, can change without a deprecation cycle, so a client integration should not assume the current parameter list is fixed.

## Conclusion

mcp-pandoc fits a team that wants an assistant to be able to turn Markdown into docx, ODT, LaTeX, EPUB, or a notebook without shelling out by hand, and that is comfortable with pandoc being installed alongside it. It is the wrong choice for a job that needs to read PDF or PPTX input, because those are write-only formats in the supported matrix, and the wrong choice if you want a single dependency, since the server pulls in pandoc itself plus a LaTeX toolchain for PDF output. Before you rely on it, read the CHEATSHEET.md in the repository for the format matrix, and check the PDF path, since the README states PDF support is still under development and declares no minimum pandoc version.

## FAQ

### What formats can the mcp-pandoc server read and write?

Markdown, HTML, docx, odt, rst, LaTeX, epub, ipynb and txt can all be both read and written. PDF and PPTX are write only. The README notes that Pandoc gained a PowerPoint reader in 3.8.3 but this project declares no minimum pandoc version, and Ubuntu 24.04 still ships pandoc 3.1.3, so pptx input is not offered.

### How do I use a defaults file with the mcp-pandoc convert-contents tool?

You pass a YAML pandoc defaults file through the `defaults_file` parameter. The README's example, an academic-paper.yaml with `from: markdown`, `to: pdf`, `number-sections: true`, `toc: true` and a metadata block, is turned into the request to convert paper.md to PDF using that defaults file and save as paper.pdf.

### Does mcp-pandoc need anything else installed besides Python?

Yes. It depends on the `pandoc` Python package family, and the Dockerfile installs `pandoc` together with `texlive-xetex`, which is what the PDF output path needs. The project requires Python 3.11 or newer and is installed with `pip install .`, with a console entry point named `mcp-pandoc`.

### Can mcp-pandoc read a PDF file?

No. PDF is a write only format in the supported matrix because Pandoc has never shipped a PDF reader. The README also states that PDF support is under development, and that the functionality and available tools are subject to change while the project is in early development.

### How do I apply a custom filter such as Mermaid in mcp-pandoc?

The `filters` parameter takes an array of pandoc filter paths to apply during the conversion. The README gives the example of converting docs.md to HTML with a filter at a path such as `/path/to/mermaid-filter.py` and saving the result as docs.html.

## Sources

- [License: MIT](https://github.com/vivekVells/mcp-pandoc/blob/main/LICENSE)
- [Project website](https://pypi.org/project/mcp-pandoc)
- [README](https://github.com/vivekVells/mcp-pandoc/blob/main/README.md)
- [Releases](https://github.com/vivekVells/mcp-pandoc/releases)
- [vivekVells/mcp-pandoc on GitHub](https://github.com/vivekVells/mcp-pandoc)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vivekvells-mcp-pandoc