mcp-docgen

A Markdown-driven Model Context Protocol (MCP) server to create, read, edit and convert Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF and HTML documents.

Built entirely on mature, permissively-licensed Python libraries (python-docx, python-pptx, openpyxl, reportlab, pypdf, markdown-it-py, markdownify, beautifulsoup4) — no proprietary dependencies. MIT licensed.

Part of the Touka project: giving AI agents the ability to produce, read and edit real Office documents using only open-source building blocks.

Why

LLMs are great at producing Markdown. mcp-docgen converts Markdown to polished Office documents — and reads them back to Markdown — so an MCP-capable assistant (Claude Desktop, Touka, …) can run a full read → edit → write loop on real .docx / .xlsx / .pptx / .pdf / .html files, and convert between any of them.

Install & run

uvx mcp-docgen          # once published to PyPI
# or, from a local checkout:
uv sync && uv run mcp-docgen

The server speaks MCP over stdio.

MCP client configuration

{
  "mcpServers": {
    "docgen": {
      "command": "uvx",
      "args": ["mcp-docgen"],
      "env": { "MCP_DOCGEN_OUTPUT_DIR": "/absolute/path/to/workdir" }
    }
  }
}

From a local checkout, swap the command for:

{ "command": "uv", "args": ["run", "--directory", "/path/to/mcp-docgen", "mcp-docgen"] }

Tools

Create (Markdown / structured data → file)

Markdown features: headings, bold / italic / inline code, bullet & numbered lists (nested), tables, block quotes, fenced code blocks, horizontal rules.

PowerPoint slide convention: # Heading starts a new slide (its title); content below becomes bullet points; --- forces a slide break; title adds a leading title slide.

Excel sheets: [{ "name": str, "rows": [[cell, …], …], "header"?: bool }]. Cells may be strings / numbers / booleans / null, or { "formula": "=SUM(A1:A2)" } for a live formula (a plain =… string is kept as inert text); the first row is a bold, frozen header unless "header": false.

Read (file → Markdown / structured data)

Reading docx/pptx to Markdown enables editing without in-place tools: read → edit the Markdown → create_* to regenerate.

Edit (in-place, preserving the rest)

edits = { "set_cells": [{"sheet","cell","value"}], "append_rows": [{"sheet","rows"}], "add_sheet": [{"name","rows"}] }. Any cell value may be { "formula": "=…" } for a live formula.

PDF page operations

Note on PDF "editing": clean open-source PDF editing means page operations (merge / split / extract), not reflowing or replacing body text — PDFs are not designed for in-place text editing. To revise PDF content, regenerate with create_pdf.

Create/edit tools return {"path": <absolute path>}; pdf_split returns {"paths": […]}.

Convert (any format → any format)

Conversions among html / docx / pptx read straight into a rich intermediate model, so colour, font, size, alignment, images and table cell spans survive — no lossy Markdown round-trip. xlsx → xlsx is lossless (styles, formulas, merges). Other pairings degrade gracefully. The result reports an honest fidelity plus a warnings list of what that particular pairing drops:

Honest limits: a PDF source is plain text (the open-source ceiling); Markdown can't carry styling, so any .md step is structure-only. A few write-side gaps remain (docx cell shading), and only inline-style HTML is read.

convert_document returns { "path", "source_format", "target_format", "fidelity", "warnings" }.

Directories & safety

• Output files are written inside MCP_DOCGEN_OUTPUT_DIR (default ./out).
• Input files (read / edit) are read from MCP_DOCGEN_INPUT_DIR (default = the output dir), so a read → edit → write loop shares one working directory.
• Every tool accepts an optional base_dir to use as the root for that single call (it roots both reads and writes), e.g. a host that jails each call to one user's directory. When MCP_DOCGEN_INPUT_DIR is configured, a per-call base_dir may only narrow within it — one that escapes the configured boundary is rejected.
• Every path is interpreted relative to its base; any path escaping it (via .. or an absolute path) is rejected, missing inputs and wrong suffixes raise errors.
• When a per-call base_dir is supplied without MCP_DOCGEN_INPUT_DIR set, it is trusted as given — the host is responsible for validating it (the trust boundary is the host). A host that would rather fail closed can set MCP_DOCGEN_STRICT_BASE_DIR=1 to cap any base_dir at the output root even when no input root is configured.
• The server makes no network calls and spawns no subprocesses.
• Generated output is hardened against injection from untrusted source content: HTML text, inline styles and URLs are escaped / scheme-allowlisted, and spreadsheet text that looks like a formula (=…) is neutralized so it can't execute in Excel.
• Process only trusted input files. Documents are parsed by third-party libraries (python-docx, openpyxl, python-pptx, pypdf); a hostile archive could attempt a decompression / XML-expansion bomb. Keep the pinned dependency versions current.

Examples

uv run python examples/generate_samples.py   # create report.docx / review.pptx / sales.xlsx
uv run python examples/roundtrip_demo.py      # create → read → edit → PDF → convert round-trip

Development

uv sync
uv run pytest
uv run ruff check .

License

MIT © 2026 Touka Project — see LICENSE.

Powered by python-docx, python-pptx, openpyxl, reportlab and pypdf; Markdown parsing by markdown-it-py; HTML reading by markdownify and BeautifulSoup. All MIT/BSD licensed.