# pandoc-mcp-server

An [MCP](https://modelcontextprotocol.io/) server that exposes [pandoc](https://pandoc.org/) document conversion as tools, deployable to [Render](https://render.com/).

## Tools

| Tool | Description |
| --- | --- |
| `convert` | Convert a document between formats using pandoc. Supports text and binary (base64) input/output. |
| `list_formats` | List the input and output formats supported by the installed pandoc. |
| `pandoc_version` | Return the installed pandoc version. |

### `convert` parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `content` | string | Source document content (text, or base64 when `content_is_base64` is true). |
| `input_format` | string | Pandoc source format (e.g. `markdown`, `html`, `docx`). Use `auto` to autodetect. |
| `output_format` | string | Pandoc target format (e.g. `html`, `gfm`, `docx`, `pdf`). |
| `standalone` | bool | Emit a complete standalone document (`--standalone`). |
| `options` | string[] | Extra pandoc options (e.g. `["--toc", "--number-sections"]`). |
| `content_is_base64` | bool | Treat `content` as base64-encoded bytes (binary inputs). |
| `output_is_base64` | bool | Return output base64-encoded (binary outputs). Falls back to base64 automatically if the result is not valid UTF-8. |

> **Note on PDF:** `pdf` output requires a PDF engine (LaTeX/wkhtmltopdf) which is not installed in the default image. Add one to the Dockerfile if you need PDF output.

## Run locally

```bash
pip install -r requirements.txt
python server.py
```

The server listens on `http://localhost:8000` (or `$PORT` if set):
- MCP endpoint: `http://localhost:8000/mcp`
- Health check: `http://localhost:8000/health`

## Deploy to Render

1. Push this repo to GitHub/GitLab/Bitbucket.
2. In the Render dashboard, choose **New > Blueprint** and select your repo. Render detects `render.yaml` and creates a Docker web service.
3. After the first deploy, your server is live at `https://<service-name>.onrender.com/mcp`.

### Connect from an MCP client (Devin CLI)

```bash
devin mcp add pandoc https://<service-name>.onrender.com/mcp
```

## Configuration

| Env var | Default | Description |
| --- | --- | --- |
| `PORT` | `8000` | Port the server binds to (set automatically by Render). |
| `PANDOC_BIN` | `pandoc` | Path to the pandoc executable. |
| `PANDOC_TIMEOUT` | `120` | Per-conversion timeout in seconds. |
| `MCP_ALLOWED_HOSTS` | unset | Comma-separated allowed Host header values. When unset, DNS-rebinding protection is disabled (safe behind Render's reverse proxy). Set this to your custom domain for production, e.g. `mcp.example.com`. |
| `MCP_ALLOWED_ORIGINS` | unset | Comma-separated allowed Origin header values for browser clients. |
| `MCP_BEARER_TOKEN` | unset | Bearer token required on `/mcp` requests (`Authorization: Bearer <token>`). When unset, the endpoint is unauthenticated. `/health` stays public. |