Typst MCP Server

Typst MCP 服务

Typst MCP 服务是 MCP（Model Context Protocol） 的一种实现，可帮助 AI 模型与 Typst 交互。Typst 是一种基于标记语言的排版系统。该服务提供了在 LaTeX 和 Typst 之间转换、验证 Typst 语法以及根据 Typst 代码生成图像的工具。

可用工具

⚠️ 目前，所有功能都通过 tools 实现，因为 Cursor 和 VS Code 还无法处理其他原语。

该服务提供以下工具：

1. list_docs_chapters()：列出 Typst 文档中的所有章节。

   • 让大模型了解文档概况并选择要阅读的章节。
   • 大模型应根据当前任务选择相关章节阅读。

2. get_docs_chapter(route)：从 Typst 文档中获取特定章节。

   • 根据大模型选择的章节，此工具会获取该章节的内容。
   • 也可使用 get_docs_chapters(routes: list) 一次获取多个章节。

3. latex_snippet_to_typst(latex_snippet)：使用 Pandoc 将 LaTeX 代码转换为 Typst。

   • 大模型更擅长编写 LaTeX 而非 Typst，因此此工具可帮助将 LaTeX 代码转换为 Typst。
   • 也可使用 latex_snippets_to_typst(latex_snippets: list) 一次转换多个 LaTeX 代码片段。

4. check_if_snippet_is_valid_typst_syntax(typst_snippet)：验证 Typst 代码。

   • 将 Typst 代码发送给用户之前，大模型应检查代码是否有效。
   • 也可使用 check_if_snippets_are_valid_typst_syntax(typst_snippets: list) 一次验证多个 Typst 代码片段。

5. typst_to_image(typst_snippet)：将 Typst 代码渲染为 PNG 图像。

   • 将复杂的 Typst 插图发送给用户之前，大模型应将代码渲染为图像并检查效果是否正确。
   • 仅适用于多模态模型。

开始使用

• 克隆此仓库

  • git clone https://github.com/johannesbrandenburger/typst-mcp.git

• 克隆 typst 仓库

  • git clone https://github.com/typst/typst.git

• 在 typst 仓库中运行文档生成命令

  • cargo run --package typst-docs -- --assets-dir ../typst-mcp/typst-docs --out-file ../typst-mcp/typst-docs/main.json
    • 请确保将路径调整为本地克隆的 typst-mcp 仓库路径
    • 此操作将在 typst-docs 文件夹中生成 main.json 和资源文件

• 安装所需依赖：uv sync（如果尚未安装，请安装 uv）

• 安装 Typst

运行服务

本地安装

执行服务脚本：

python server.py

或者通过 MCP 将其安装到 Claude Desktop：

mcp install server.py

或者在 VS Code 中使用新的 Agent 模式：

Agent 模式：面向所有用户开放并支持 MCP

Docker

有关 Docker 安装和使用的详细构建信息及说明，请参阅 DOCKER.md。

平台配置

此 MCP 服务可与各种 AI 编码平台集成。以下是常见平台的配置说明：

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "typst": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ]
    }
  }
}

或者用于本地安装：

{
  "mcpServers": {
    "typst": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ]
    }
  }
}

Cursor

在项目根目录中创建 .cursor/mcp.json，进行项目级配置：

{
  "mcpServers": {
    "typst": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ]
    }
  }
}

或者创建 ~/.cursor/mcp.json 进行全局配置。本地安装请使用：

{
  "mcpServers": {
    "typst": {
      "command": "python",
      "args": ["/path/to/typst-mcp/server.py"]
    }
  }
}

Roo Code

在项目根目录中创建 .roo/mcp.json，进行项目级配置：

{
  "mcpServers": {
    "typst": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ]
    }
  }
}

或者通过 Roo Code MCP 设置视图编辑全局设置。本地安装请使用：

{
  "mcpServers": {
    "typst": {
      "command": "python",
      "args": ["/path/to/typst-mcp/server.py"]
    }
  }
}

OpenCode

在项目根目录中创建或编辑 opencode.json 文件：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "typst": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", 
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ],
      "enabled": true
    }
  }
}

本地安装：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "typst": {
      "type": "local",
      "command": ["python", "/path/to/typst-mcp/server.py"],
      "enabled": true
    }
  }
}

Claude Code

在 Claude Code 设置文件（~/.claude/settings.json）中配置 MCP 服务：

{
  "mcpServers": {
    "typst": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ]
    }
  }
}

或用于本地安装：

{
  "mcpServers": {
    "typst": {
      "command": "python",
      "args": ["/path/to/typst-mcp/server.py"]
    }
  }
}

使用 Agent Mode 的 VS Code

VS Code 的 Agent Mode 原生支持 MCP（无需扩展）：

1. 在 VS Code 设置（chat.agent.enabled）中启用 Agent Mode
2. 在工作区中创建 .vscode/mcp.json：

{
  "servers": {
    "typst": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/johannesbrandenburger/typst-mcp:latest"
      ]
    }
  }
}

如需全局配置，请通过 MCP: Open User Configuration 命令将配置添加到用户配置文件中。

Typst 文档的 JSON Schema

⚠️ Typst 文档的 Schema 并不稳定，可能随时变化。该 Schema 根据 Typst 源代码生成，不保证完整或准确。如果 Schema 发生变化，则需要相应地更新此仓库，以便文档功能恢复正常。