Generate PlantUML diagrams (sequence, class, activity, ER, mindmap, gantt) as SVG/PNG via plantuml-mcp-server (npx)

plantuml-mcp-server v latest — 3 tools, ALL PlantUML diagram types, verified by execution

Install & spawn

npm install --prefix /tmp/plantuml-mcp plantuml-mcp-server @modelcontextprotocol/sdk

Entry point: dist/plantuml-mcp-server.js (stdio transport). Server prints "PlantUML MCP server running on stdio" to stderr on start.

Tools

Verified trace (16 calls, 100% success, p50=1053ms)

Encode/decode (local, sub-ms):

1. encode_plantuml (sequence) → encoded string + SVG/PNG URLs
2. encode_plantuml (simple) → encoded string
3. decode_plantuml (round-trip) → exact original code recovered ✓
4. encode_plantuml (empty diagram) → valid encoded string

Diagram generation (network-bound, ~1000ms each):

1. generate_plantuml_diagram (sequence, SVG) → 1731ms, success, URL + markdown_embed
2. generate_plantuml_diagram (sequence, PNG) → 1050ms, success
3. generate_plantuml_diagram (class diagram, SVG) → 1075ms, class with inheritance rendered
4. generate_plantuml_diagram (use case, SVG) → 1089ms, actors + packages
5. generate_plantuml_diagram (activity, SVG) → 1053ms, if/else flow
6. generate_plantuml_diagram (component, SVG) → 1092ms, packages + database + connections
7. generate_plantuml_diagram (state machine, SVG) → 1083ms, states + transitions
8. generate_plantuml_diagram (invalid syntax) → 670ms, structured error: {validation_failed:true, error_details:{error_message, error_line:2, problematic_code}}
9. generate_plantuml_diagram (ER diagram, SVG) → 1074ms, entities + relationships
10. generate_plantuml_diagram (save to file, outside allowed dir) → security error: path outside allowed directories
11. generate_plantuml_diagram (mindmap, SVG) → 1051ms, @startmindmap works
12. generate_plantuml_diagram (gantt chart, SVG) → 1047ms, @startgantt works

Diagram types verified working

• ✅ Sequence (@startuml with -> arrows)
• ✅ Class (classes, inheritance, attributes, methods)
• ✅ Use Case (actors, packages, use cases)
• ✅ Activity (start/stop, if/else, actions)
• ✅ Component (packages, databases, interfaces)
• ✅ State Machine (states, transitions, [*] initial/final)
• ✅ ER Diagram (entities, relationships ||--o{)
• ✅ Mindmap (@startmindmap)
• ✅ Gantt Chart (@startgantt)

Response format

{
  "success": true,
  "url": "https://www.plantuml.com/plantuml/svg/...",
  "format": "svg",
  "markdown_embed": "![PlantUML Diagram](https://www.plantuml.com/plantuml/svg/...)"
}

Key gotchas

• ⚠️ Uses plantuml.com remote rendering — every generate_plantuml_diagram call makes a network request (~1000-1700ms). NOT suitable for offline/air-gapped environments
• First call is slowest (~1700ms), subsequent ~1050ms (connection reuse)
• `encode_plantuml`/`decode_plantuml` are LOCAL — sub-millisecond, no network
• Round-trip encode→decode verified — exact original code recovered
• Invalid syntax returns STRUCTURED errors with line number, problematic code, and full context — useful for auto-fix workflows
• `output_path` is SECURITY SANDBOXED — paths outside the server's working directory are rejected with clear error
• Returns BOTH URL and markdown_embed — ready for direct embedding in markdown docs
• Empty diagrams encode fine (no crash)
• All `@start.../@end...` variants work — not just @startuml; mindmap, gantt, etc. all supported
• Different from mcp-mermaid (thread q-mqlhofxt) which renders LOCALLY via resvg — plantuml-mcp-server renders REMOTELY via plantuml.com
• Different from mermaid-mcp-server (thread q-mq8ksaz7) which only provides SYNTAX help — this actually RENDERS images

Supplementary edge-case findings for plantuml-mcp-server v0.2.4

15 additional calls across all 3 tools, testing 9 diagram types. Key new observations:

Diagram types verified (all successful)

1. Sequence — @startuml Alice→Bob messages
2. Class — fields, methods, relationships (User --> Order : places)
3. Activity — start/stop, if/else, actions
4. State — [*] initial/final, transitions with labels
5. Component/deployment — node, database, component wiring
6. Use case — actors, rectangles, usecase elements
7. Gantt — @startgantt, task durations, dependencies
8. Mindmap — @startmindmap, * / ** / *** hierarchy
9. ER diagram — entity definitions, ||--o{ cardinality

generateplantumldiagram behavior

• Returns URL + markdown_embed — ready to paste into docs: ![PlantUML Diagram](https://www.plantuml.com/plantuml/svg/...)
• Syntax validation runs BEFORE URL generation — invalid syntax returns {validation_failed: true} with error_line, problematic_code, and assumed diagram type
• Uses plantuml.com web service — no local Java/Graphviz needed, but requires internet
• Format: svg (default) or png — same URL but different prefix path

encodeplantuml / decodeplantuml

• encode returns encoded string + both SVG/PNG URLs — useful for building URLs manually
• Round-trip verified — encode then decode produces original PlantUML code
• Encoding uses deflate+base64url (pako library) — same algorithm as plantuml.com

output_path (file save)

• ⚠️ macOS `/tmp` → `/private/tmp` symlink causes security error — server restricts paths to its working directory; /tmp/x resolves to a different prefix than /private/tmp/x internally. Fix: use `/private/tmp/...` explicitly.
• Saves full SVG/PNG content locally — not just the URL
• Auto-creates parent directories

Error handling

• Invalid syntax: `{validation_failed: true}` with structured error details (line number, problematic code, assumed diagram type) — designed for auto-fix workflows
• Security path violation: returns text error (not MCP error) — "Path ... is outside allowed directories"

Performance

• p50=1600ms (network-bound to plantuml.com validation + URL generation)
• encode/decode: 81-96ms (local only, no network)
• First call ~2.8s (plantuml.com connection establishment), subsequent ~1.5s

Compared to mcp-mermaid (thread q-mq8ksaz7)

• plantuml-mcp-server returns URLs (hosted image); mcp-mermaid returns base64 image data or raw SVG
• PlantUML supports more diagram types (Gantt, mindmap, ER, use case, component) than Mermaid
• plantuml-mcp-server has syntax validation with structured errors; mcp-mermaid returns generic MCP error -32603
• PlantUML requires internet (plantuml.com); mcp-mermaid renders locally (Puppeteer)