Trellis MCP Server

The Trellis MCP server exposes diagram rendering as a tool for Claude Desktop and other MCP-compatible clients. It wraps the trellis CLI binary and supports both stdio and HTTP transports.

Built with FastMCP.

Prerequisites

Python 3.10+
trellis binary installed and accessible
pip install fastmcp prefab-ui

Installation

# Clone or navigate to the mcp/ directory
cd trellis/mcp/

# Install dependencies
pip install -r requirements.txt

requirements.txt contents:

fastmcp
prefab-ui

Environment variables

Variable	Default	Description
`TRELLIS_BIN`	`./trellis`	Path to the `trellis` binary
`TRELLIS_MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`TRELLIS_KEY`	—	License key. Required for `svg`, `html`, and `drawio` output

Use an absolute path for TRELLIS_BIN in production:

export TRELLIS_BIN=/usr/local/bin/trellis

A TRELLIS_KEY is required for SVG, HTML, and Draw.io output. See Licensing for the subscribe link and key setup.

Running the server

stdio (for MCP clients)

python server.py

The server communicates over stdin/stdout. MCP clients connect via the Claude Desktop config (see below).

HTTP (for testing and debugging)

TRELLIS_MCP_TRANSPORT=http python server.py
# Listens on http://127.0.0.1:9000

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your platform:

{
  "mcpServers": {
    "trellis": {
      "command": "python",
      "args": ["/path/to/trellis/mcp/server.py"],
      "env": {
        "TRELLIS_MCP_TRANSPORT": "stdio",
        "TRELLIS_BIN": "/usr/local/bin/trellis",
        "TRELLIS_KEY": "YOUR_KEY"
      }
    }
  }
}

Replace /path/to/trellis/mcp/server.py, /usr/local/bin/trellis, and YOUR_KEY with the actual values on your system.

Tools

`render`

Renders a Mermaid diagram string and returns the result. PNG is returned as a base64-encoded image; all other formats are returned as text.

Parameters:

Parameter	Type	Default	Description
`mermaid`	string	required	Mermaid diagram source
`format`	string	`png`	Output format: `svg`, `png`, `html`, `drawio`
`theme`	string	`default`	Theme name: `default`, `paper`, `blueprint`, `dark`, `midnight`, `forest`

Returns: Image content for PNG; text content for SVG, HTML, and Draw.io.

Choosing a format (by goal):

Format	Best for	License
`html`	Interactive review — exploring/navigating a diagram in a browser	Required
`drawio`	Editing the diagram further in Draw.io	Required
`svg`	Quick, high-quality preview or web embedding	Required
`png`	Unlicensed users, or a plain fixed-size raster image	Not required

If no TRELLIS_KEY is set, use png (the default).

SVG, HTML, and Draw.io output require a TRELLIS_KEY. See Licensing.

Example — ask Claude:

“Render this as a Trellis diagram: flowchart LR User --> API --> DBs ”

Resources

`themes://list`

Returns a JSON array of available themes with names and descriptions.

[
  {"name": "default",   "description": "Default Trellis theme"},
  {"name": "paper",     "description": "Paper theme"},
  {"name": "blueprint", "description": "Blueprint theme"},
  {"name": "dark",      "description": "Dark theme"},
  {"name": "midnight",  "description": "Midnight theme"},
  {"name": "forest",    "description": "Forest theme"}
]

`formats://list`

Returns a JSON array of available output formats with descriptions.

[
  {"name": "png",    "description": "(Default) Raster image result"},
  {"name": "svg",    "description": "Vector image result"},
  {"name": "html",   "description": "Interactive HTML output"},
  {"name": "drawio", "description": "Drawio output format for further editing"}
]

Format purposes and details: CLI Reference → Output formats.

Prompts

The server registers MCP prompts that surface in clients (e.g. Claude Desktop) as slash-command-style helpers. They guide diagram authoring toward Trellis-specific features.

Prompt	Arguments	Purpose
`c4_cheatsheet`	—	Reference for all C4 node types, including Trellis-specific shapes and argument order
`c4_pick_shape`	`element`	Map a plain-English element description to the right C4 node type
`output_format_guide`	—	Pick the right render output format for the user’s goal

The same guidance is also baked into the server’s connection instructions, so clients that honor instructions receive it automatically without invoking a prompt.

C4 node types

Trellis supports standard Mermaid C4 plus Trellis-specific container shapes (use in C4Container / C4Component diagrams). Prefer the specific shape over a generic Container when it matches an element’s role.

Type	Use for
`ContainerFrontend`	Web UI / browser app (chrome bar)
`ContainerApp`	Desktop / mobile app
`ContainerFolder`	File / config store (folder tab)
`ContainerGateway`	API gateway / router
`ContainerBucket`	Object storage (S3-like)

Each also has a _Ext variant for external / third-party systems.

Standard types: Person, System(Db|Queue), Container(Db|Queue), Component(Db|Queue) — all with _Ext variants. Boundaries: Enterprise_Boundary, System_Boundary, Container_Boundary, Deployment_Node. Relations: Rel, BiRel, Rel_U/Rel_D/Rel_L/Rel_R, Rel_Back — Rel(from, to, label[, tech]).

Argument order:

System / Person: (alias, label, description)
Container / Component: (alias, label, technology, description)

Usage examples

Flowchart

flowchart LR
  User -->|HTTP| API
  API -->|SQL| DB
  API -->|Cache| Redis

Class diagram

classDiagram
  Animal <|-- Dog
  Animal <|-- Cat
  Animal : +String name
  Animal : +speak()
  Dog : +fetch()
  Cat : +purr()

ER diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  PRODUCT ||--o{ LINE-ITEM : "included in"

C4 architecture diagram

C4Context
  title System Overview
  Person(user, "User", "A customer")
  System(web, "Web App", "Frontend")
  System_Ext(auth, "Auth Service", "OAuth provider")
  Rel(user, web, "Uses")
  Rel(web, auth, "Authenticates via")

C4 container diagram (Trellis-specific shapes)

C4Container
  title Web Platform — Containers
  Person(user, "User", "A customer")
  ContainerFrontend(spa, "Web UI", "React", "Single-page app")
  ContainerGateway(gw, "API Gateway", "Kong", "Routes traffic")
  Container(api, "API", "Rust/Actix", "Business logic")
  ContainerDb(db, "Database", "PostgreSQL", "Stores data")
  ContainerBucket(assets, "Assets", "S3", "Static files")
  Rel(user, spa, "Uses")
  Rel(spa, gw, "Calls", "HTTPS")
  Rel(gw, api, "Routes to")
  Rel(api, db, "Reads/writes")
  Rel(api, assets, "Stores objects")