doc2images-mcp

An MCP server that renders documents to images and returns them directly as multimodal content for the model.

• Deterministic "document -> image" conversion only;
• Does not convert documents to Markdown and does not do LLM-based document understanding / OCR;
• PDF rendering is handled by pypdfium2 (PDFium), a self-contained Python wheel with no external binaries. PDFium ships its own encoding data, including the CJK CMaps, so Chinese/Japanese/Korean text renders correctly.

This version supports PDF only. The DOCX / PPTX branch is reserved in the code and will be enabled once LibreOffice is wired in.

Requirements

No system packages are required: pypdfium2 bundles the PDFium binaries.

Install

uv tool install doc2images-mcp

Wiring it into OpenCode

Add the following to the mcp.servers section of opencode.jsonc:

"doc2images": {
  "type": "local",
  "command": [
    "uvx",
    "doc2images-mcp",
  ],
},

To cap how much image data reaches the context, you can also tighten OpenCode's image settings:

"media": {
  "image": {
    "auto_resize": true,
    "max_width": 2000,
    "max_height": 2000,
    "max_base64_bytes": 5242880,
  },
},

Tool: pdf_to_images

Renders PDF pages and returns a list of images (one per page).

Environment variables

Testing

Sample PDFs live in data/; the tests render them through the tool:

uv run pytest -v

Rendered intermediate images are written to tmp/, which is ignored via its own .gitignore.

Roadmap

• Office support: after installing LibreOffice, add soffice --headless --convert-to pdf for .docx/.pptx/.ppt in the dispatch function, then reuse the same rendering logic.
• Embedded image extraction: extract only the images embedded in a document instead of whole pages.
• Alternative backend: PyMuPDF (fitz) is a drop-in alternative if its richer text/embedded-image APIs are ever needed; the tool interface stays the same.