# Typst MCP Server

Use this skill when an agent needs to render, convert, validate, or improve Typst documents through the public Typst MCP Server at `https://typst.grenz.net/mcp`.

The server also exposes an optional ChatGPT Apps UI through `open_typst_renderer`, but all core workflows should continue to use the normal MCP tools so Claude, Codex, and other clients remain compatible.

## When To Use

- Render complete Typst source to PDF, SVG, or PNG.
- Convert Markdown, GitHub-Flavored Markdown, HTML, or complete LaTeX documents to editable Typst.
- Convert Markdown, HTML, or LaTeX and render directly to PDF, SVG, or PNG.
- Validate Typst snippets before showing final Typst code to a user.
- Convert LaTeX snippets to Typst through Pandoc.
- Read official Typst documentation chapters before writing unfamiliar Typst syntax.
- Render a `.typ` file from an MCP file object, a public HTTPS URL, an allowed server path, or inline source.
- Open the optional ChatGPT UI when the host supports Apps SDK widgets and the user benefits from an interactive form.

## Endpoint

```json
{
  "type": "streamable-http",
  "url": "https://typst.grenz.net/mcp"
}
```

## Recommended Workflow

1. Use `list_docs_chapters` when the task depends on Typst syntax or APIs you are not fully sure about.
2. Retrieve the relevant docs with `get_docs_chapter` or `get_docs_chapters`.
3. If the user provides Markdown, HTML, or LaTeX and wants editable source, call `convert_document_to_typst` first.
4. If the user provides Markdown, HTML, or LaTeX and only wants a file, call `render_converted_document`.
5. Draft or edit Typst source directly when the input is already Typst.
6. Validate short snippets with `check_if_snippet_is_valid_typst_syntax`.
7. Render final Typst documents with `render_typst`, `render_typst_from_template`, or `render_typst_file`.
8. Return the tokenized download URL to the user and mention when it expires if relevant.

## Document Conversion Workflow

Use `convert_document_to_typst` when the user needs Typst source they can inspect, edit, or reuse. Set `input_format` explicitly to `markdown`, `gfm`, `html`, or `latex`; do not guess from the filename when the user already told you the format.

Use `render_converted_document` when the user asks for a final PDF, SVG, or PNG from Markdown, HTML, or LaTeX. The tool converts with Pandoc, renders with Typst, and includes the converted Typst in `structuredContent.typst` for debugging.

## Render Lifespan

Rendered files are temporary. Rendering tools accept optional `lifespan_hours`; omit it for the default 6-hour lifespan or set it up to 48 hours when the user needs a longer-lived link. The response includes `expiresAt`.

Render tokens are generated per output file and survive service restarts until expiry because the server persists token metadata locally. A download only works when `/renders/<file>` receives the matching `token` query parameter.

## File Upload Caveat

ChatGPT-style local file paths such as `/mnt/data/example.typ` are client-side paths. Some MCP bridges transform those paths into uploaded file objects with a `download_url`; others pass the path as plain text. If the server receives a plain client-side path, it cannot read it. Use inline `source`, a public HTTPS `.typ` URL, or a real uploaded file object when file bridging is unavailable.

## Available Tool Groups

- Rendering: `render_typst`, `render_typst_from_template`, `render_typst_file`
- Optional UI: `open_typst_renderer`
- Documentation: `list_docs_chapters`, `get_docs_chapter`, `get_docs_chapters`
- Conversion: `latex_snippet_to_typst`, `latex_snippets_to_typst`, `convert_document_to_typst`, `render_converted_document`
- Validation: `check_if_snippet_is_valid_typst_syntax`, `check_if_snippets_are_valid_typst_syntax`

## Final Output Guidance

Before sending Typst code as a final answer, validate it when practical. If rendering is requested, return the MCP resource link and token-protected rendered file URL. Render URLs are temporary and expire according to the selected lifespan.