Typst MCP Server

1# Typst MCP Server
2 
3Typst MCP Server is an [MCP (Model Context Protocol)](https://github.com/modelcontextprotocol) implementation that helps AI models interact with [Typst](https://github.com/typst/typst), a markup-based typesetting system. The server provides tools for converting between LaTeX and Typst, validating Typst syntax, and generating images from Typst code.
4 
5## Available Tools
6 
7>⚠️ Currently all the functionality is implemented as `tools`, because Cursor and VS Code are not able to handle the other primitives yet.
8 
9The server provides the following tools:
10 
111. **`list_docs_chapters()`**: Lists all chapters in the Typst documentation.
12   - Lets the LLM get an overview of the documentation and select a chapter to read.
13   - The LLM should select the relevant chapter to read based on the task at hand.
14 
152. **`get_docs_chapter(route)`**: Retrieves a specific chapter from the Typst documentation.
16   - Based on the chapter selected by the LLM, this tool retrieves the content of the chapter.
17   - Also available as `get_docs_chapters(routes: list)` for retrieving multiple chapters at once.
18 
193. **`latex_snippet_to_typst(latex_snippet)`**: Converts LaTeX code to Typst using Pandoc.
20   - LLMs are better at writing LaTeX than Typst, so this tool helps convert LaTeX code to Typst.
21   - Also available as `latex_snippets_to_typst(latex_snippets: list)` for converting multiple LaTeX snippets at once.
22 
234. **`check_if_snippet_is_valid_typst_syntax(typst_snippet)`**: Validates Typst code.
24   - Before sending Typst code to the user, the LLM should check if the code is valid.
25   - Also available as `check_if_snippets_are_valid_typst_syntax(typst_snippets: list)` for validating multiple Typst snippets at once.
26 
275. **`typst_to_image(typst_snippet)`**: Renders Typst code to a PNG image.
28   - Before sending complex Typst illustrations to the user, the LLM should render the code to an image and check if it looks correct.
29   - Only relevant for multi modal models.
30 
31## Getting Started
32 
33- Clone this repository
34  - `git clone https://github.com/johannesbrandenburger/typst-mcp.git`
35- Clone the [typst repository](https://github.com/typst/typst.git)
36  - `git clone https://github.com/typst/typst.git`
37- Run the docs generation in the typst repository
38  - `cargo run --package typst-docs -- --assets-dir ../typst-mcp/typst-docs --out-file ../typst-mcp/typst-docs/main.json`
39    - Make sure to adjust the path to your local clone of the typst-mcp repository
40    - This will generate the `main.json` and the assets in the `typst-docs` folder
41- Install required dependencies: `uv sync` (install [uv](https://github.com/astral-sh/uv) if not already installed)
42  
43- Install Typst
44 
45## Running the Server
46 
47### Local Installation
48 
49Execute the server script:
50 
51```bash
52python server.py
53```
54 
55Or install it in Claude Desktop with MCP:
56 
57```bash
58mcp install server.py
59```
60 
61Or use the new agent mode in VS Code:
62 
63[Agent mode: available to all users and supports MCP](https://code.visualstudio.com/blogs/2025/04/07/agentMode)
64 
65### Docker
66 
67For Docker installation and usage, see [DOCKER.md](DOCKER.md) for detailed build information and instructions.
68 
69## Platform Configuration
70 
71This MCP server can be integrated with various AI coding platforms. Below are configuration instructions for popular platforms:
72 
73### Claude Desktop
74 
75Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):
76 
77**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
78**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
79 
80```json
81{
82  "mcpServers": {
83    "typst": {
84      "command": "docker",
85      "args": [
86        "run", "--rm", "-i",
87        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
88      ]
89    }
90  }
91}
92```
93 
94Or for local installation:
95 
96```json
97{
98  "mcpServers": {
99    "typst": {
100      "command": "docker",
101      "args": [
102        "run", "--rm", "-i",
103        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
104      ]
105    }
106  }
107}
108```
109 
110### Cursor
111 
112Create `.cursor/mcp.json` in your project root for project-specific configuration:
113 
114```json
115{
116  "mcpServers": {
117    "typst": {
118      "command": "docker",
119      "args": [
120        "run", "--rm", "-i",
121        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
122      ]
123    }
124  }
125}
126```
127 
128Or create `~/.cursor/mcp.json` for global configuration. For local installation:
129 
130```json
131{
132  "mcpServers": {
133    "typst": {
134      "command": "python",
135      "args": ["/path/to/typst-mcp/server.py"]
136    }
137  }
138}
139```
140 
141### Roo Code
142 
143Create `.roo/mcp.json` in your project root for project-specific configuration:
144 
145```json
146{
147  "mcpServers": {
148    "typst": {
149      "command": "docker",
150      "args": [
151        "run", "--rm", "-i",
152        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
153      ]
154    }
155  }
156}
157```
158 
159Or edit global settings via Roo Code MCP settings view. For local installation:
160 
161```json
162{
163  "mcpServers": {
164    "typst": {
165      "command": "python",
166      "args": ["/path/to/typst-mcp/server.py"]
167    }
168  }
169}
170```
171 
172### OpenCode
173 
174Create or edit the `opencode.json` file in your project root:
175 
176```json
177{
178  "$schema": "https://opencode.ai/config.json",
179  "mcp": {
180    "typst": {
181      "type": "local",
182      "command": ["docker", "run", "--rm", "-i", 
183        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
184      ],
185      "enabled": true
186    }
187  }
188}
189```
190 
191For local installation:
192 
193```json
194{
195  "$schema": "https://opencode.ai/config.json",
196  "mcp": {
197    "typst": {
198      "type": "local",
199      "command": ["python", "/path/to/typst-mcp/server.py"],
200      "enabled": true
201    }
202  }
203}
204```
205 
206### Claude Code
207 
208Configure MCP servers in your Claude Code settings file (`~/.claude/settings.json`):
209 
210```json
211{
212  "mcpServers": {
213    "typst": {
214      "command": "docker",
215      "args": [
216        "run", "--rm", "-i",
217        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
218      ]
219    }
220  }
221}
222```
223 
224Or for local installation:
225 
226```json
227{
228  "mcpServers": {
229    "typst": {
230      "command": "python",
231      "args": ["/path/to/typst-mcp/server.py"]
232    }
233  }
234}
235```
236 
237### VS Code with Agent Mode
238 
239VS Code's Agent Mode has native MCP support (no extension required):
240 
2411. Enable Agent Mode in VS Code settings (`chat.agent.enabled`)
2422. Create `.vscode/mcp.json` in your workspace:
243 
244```json
245{
246  "servers": {
247    "typst": {
248      "command": "docker",
249      "args": [
250        "run", "--rm", "-i",
251        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
252      ]
253    }
254  }
255}
256```
257 
258For global configuration, add to your user profile via **MCP: Open User Configuration** command.
259 
260## JSON Schema of the Typst Documentation
261 
262>⚠️ The schema of the typst documentation is not stable and may change at any time. The schema is generated from the typst source code and is not guaranteed to be complete or correct. If the schema changes, this repository will need to be updated accordingly, so that the docs functionality works again.