AI agents (MCP)

typstgen mcp starts a Model Context Protocol server on stdin/stdout. An agent that writes Typst can then compile its own output, read the errors, look at the result and fix it, without a typst binary on the machine.

Set up

Claude Code, for the current project:

claude mcp add typstgen -- typstgen mcp --root .

Any other client that starts stdio servers uses the same command, for example in a .mcp.json:

{
  "mcpServers": {
    "typstgen": { "command": "typstgen", "args": ["mcp", "--root", "."] }
  }
}

--root is the workspace. It becomes the working directory, so typstgen.toml and its relative paths are read from there (or pass --config). Every path a tool receives is relative to the workspace, and no tool reads or writes a file outside it; imports from template directories and packages resolve as with typstgen compile.

Tools

Tool	Arguments	Returns
check	path, inputs, creation_timestamp	ok, N pages and warnings, or every error as path:line:column: error: … with hints. Writes nothing.
preview	path, page (default 1), scale (pixels per point, default 1.5), inputs, creation_timestamp	One page as a PNG image.
compile	path, output, pdf_standards (e.g. ["a-2b"]), inputs, creation_timestamp	wrote <file> (<bytes> bytes), N pages and warnings.
list_templates	–	Every .typ file in the template directories, with its first // comment as description.

Errors are tool results, not protocol errors, so the agent sees them and can react:

typst compilation failed:
bad.typ:2:2: error: unknown variable: unbekannt

A typical loop

1. The agent writes angebot.typ, importing a template it found with list_templates.
2. check reports an error with file, line and column; the agent fixes it and checks again.
3. preview shows page 1, so layout problems (overflowing tables, wrong page breaks) are visible.
4. compile with pdf_standards: ["a-2b"] and a creation_timestamp writes the archivable PDF.

Give templates a first-line comment such as // Offer with price table and terms so the agent can pick the right one from list_templates.

In practice

1. An invoice from a template: “Make invoice 2026-0142 for ACME GmbH from our template – relaunch 8,400, hosting 12 × 49, 6 support hours at 95 – and save it to out/.” list_templates finds invoice.typ by its first comment (inputs: customer, number, items); compile with those inputs writes out/invoice-2026-0142-acme.pdf (1 page), and preview shows the page.
2. A broken build: “report.typ doesn’t build anymore – fix it.” check reports report.typ:6:3: error: unexpected argument: author; the assistant removes the argument the layout no longer takes, and check returns ok, 2 pages.
3. A table off the page: “The table on page 2 runs off the page.” check had said ok, but preview of page 2 shows the table running past the right edge. After the number columns size to their content, a second preview shows it inside the text area.
4. Archiving as PDF/A: “Archive the annual report as PDF/A.” compile with pdf_standards: ["a-2b"] fails with PDF/A-2b error: document contains an attached file, pointing at the attached CSV. With ["a-3b"], which allows attachments, and a fixed creation_timestamp, it writes out/annual-report-2025.pdf (2 pages).