Typst MCP Server

The project utilizes a multi-stage build system to optimize build times:

• Base image: Contains pre-compiled Typst documentation (built from Rust nightly). This image only needs to be rebuilt when the Typst documentation itself changes.
• Runtime image: Contains the MCP server (built from Python slim) and inherits from the base image. This is the image used for standard operations and is rebuilt when the Python server code changes.

If you prefer not to use the build script, you can build the images manually using the provided Dockerfiles. The project uses a two-stage architecture:

1. Base Image: Built from Dockerfile.base, contains pre-compiled Typst documentation.
2. Runtime Image: Built from Dockerfile.runtime, contains the Python MCP server and uses the base image.

# Build base image with Typst documentation
docker build -f Dockerfile.base -t ghcr.io/johannesbrandenburger/typst-mcp-base:latest .

# Build runtime image
docker build -f Dockerfile.runtime -t ghcr.io/johannesbrandenburger/typst-mcp:latest .

To quickly start the Typst MCP server without building it locally, pull and run the pre-built image from GitHub Container Registry using the following command:

docker run --rm -i ghcr.io/johannesbrandenburger/typst-mcp:latest

The project provides a build.sh script to manage the multi-stage build process. Use these commands depending on your needs:

• Build everything: Rebuilds both the base and runtime images.
• Build runtime only: Use this when you have made changes to the Python MCP server code.
• Build base only: Use this when the Typst documentation needs updating.
• Run: Builds and then executes the container.

# Build both base and runtime images
./build.sh

# Build only runtime image (for code changes)
./build.sh runtime

# Build only base image (when docs change)
./build.sh base

# Run the container
./build.sh run

VS Code's Agent Mode supports MCP natively.

1. Enable Agent Mode: Ensure chat.agent.enabled is set to true in your VS Code settings.
2. Configure Workspace: Create a .vscode/mcp.json file in your workspace root.

Using Docker

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

For global configuration, use the MCP: Open User Configuration command in VS Code.

To integrate Typst MCP with OpenCode, create or edit an opencode.json file in your project root.

Using Docker

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

Using Local Installation

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

You can use the following docker-compose.yml configuration to manage the Typst MCP service. Note that stdin_open: true is required for the MCP server to interact correctly.

version: '3.8'
services:
  typst-mcp:
    image: ghcr.io/johannesbrandenburger/typst-mcp:latest
    stdin_open: true
    tty: false
    restart: unless-stopped

To use the Typst MCP server in Claude Desktop, add it to your claude_desktop_config.json file.

File Locations:

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

Option 1: Using Docker (Recommended)

Use the pre-built image from GitHub Container Registry:

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

Option 2: Local Installation

If you have installed the server locally, point to the server.py file:

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

You can configure Typst MCP for Cursor either globally or per-project.

Project-specific Configuration

Create a .cursor/mcp.json file in your project root.

Using Docker:

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

Using Local Installation:

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

Global Configuration

Create or edit ~/.cursor/mcp.json using the same JSON structures as above.

To configure the Typst MCP server for Claude Code, edit your settings file located at ~/.claude/settings.json.

Using Docker

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

Using Local Installation

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

To use Typst MCP with Roo Code, you can use project-specific settings or global settings.

Project-specific Configuration

Create a .roo/mcp.json file in your project root.

Using Docker:

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

Using Local Installation:

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

Alternatively, you can edit the global settings via the Roo Code MCP settings view in your IDE.