PlantUML MCP Server

What is PlantUML MCP Server about?

Provides a lightweight Node.js MCP server that accepts PlantUML source, validates it, and returns diagram images (SVG/PNG) via URLs. It also offers tools to encode/decode PlantUML strings and handles common syntax errors automatically.

How to use PlantUML MCP Server?

1. Quick setup for Claude Code

   claude mcp add plantuml --scope user --env PLANTUML_SERVER_URL=https://www.plantuml.com/plantuml -- npx plantuml-mcp-server
   

2. Quick setup for Claude Desktop – add the following to claude_desktop_config.json:

   {
     "mcpServers": {
       "plantuml": {
         "command": "npx",
         "args": ["plantuml-mcp-server"],
         "env": { "PLANTUML_SERVER_URL": "https://www.plantuml.com/plantuml" }
       }
     }
   }
   

3. Restart Claude Desktop/Code to activate the server.
4. Use the provided tools (generate_plantuml_diagram, encode_plantuml, decode_plantuml) in prompts to create, share, or fix diagrams.

Key Features of PlantUML MCP Server

• Diagram generation: Returns embeddable SVG/PNG URLs instantly.
• Local saving: output_path parameter saves diagrams within allowed directories.
• Security controls: Restricts file writes to the current working directory by default; configurable via PLANTUML_ALLOWED_DIRS.
• Encoding/decoding: URL‑friendly PlantUML string handling.
• Error handling workflow: Detects syntax errors, suggests auto‑fixes, and retries.
• Supports advanced PlantUML features: !include, external libraries, C4, sequence, class diagrams, etc.

Use Cases of PlantUML MCP Server

• AI assistants (Claude Desktop/Code) automatically generate architecture diagrams from natural‑language requests.
• Documentation pipelines that embed up‑to‑date diagrams without manual rendering.
• Learning environments where students experiment with PlantUML and receive instant visual feedback.
• CI/CD workflows that produce visual reports of system designs.

FAQ from the PlantUML MCP Server

• Q: Do I need to run my own PlantUML server? A: No, the default uses the public https://www.plantuml.com/plantuml. You can point PLANTUML_SERVER_URL to a private instance if desired.
• Q: Which file formats are allowed for local saving? A: Only .svg and .png are permitted.
• Q: How can I allow saving outside the current directory? A: Set PLANTUML_ALLOWED_DIRS to a colon‑separated list of directories or * for unrestricted access (use with caution).
• Q: What Node.js version is required? A: Node.js 18 or newer.
• Q: How do I run tests locally? A: Execute make test or make test-mcp after installing dependencies.

PlantUML MCP Server

A Model Context Protocol (MCP) server that provides PlantUML diagram generation capabilities for Claude Desktop and Claude Code.

Available Tools

1. generate_plantuml_diagram - Generate diagrams and get embeddable URLs (SVG/PNG), optionally save locally
2. encode_plantuml - Encode PlantUML code for URL sharing
3. decode_plantuml - Decode PlantUML from encoded strings

Available Prompts

1. plantuml_error_handling - Guidelines for handling PlantUML syntax errors and implementing auto-fix workflows

This prompt provides Claude instances with comprehensive instructions on how to:

• Detect PlantUML syntax errors using native server validation
• Implement intelligent auto-fix workflows for common syntax issues
• Parse structured error responses and apply appropriate corrections
• Handle validation failures gracefully with retry logic

The prompt enables Claude to automatically detect and fix common PlantUML errors like missing tags, invalid arrow syntax, typos in keywords, and missing quotes, making PlantUML diagram generation more reliable and user-friendly.

Quick Setup

For Claude Code

# Using default PlantUML server
claude mcp add plantuml --scope user --env PLANTUML_SERVER_URL=https://www.plantuml.com/plantuml -- npx plantuml-mcp-server

For Claude Desktop

Add this to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "plantuml": {
      "command": "npx",
      "args": ["plantuml-mcp-server"],
      "env": {
        "PLANTUML_SERVER_URL": "https://www.plantuml.com/plantuml"
      }
    }
  }
}

To use your own PlantUML server, change the PLANTUML_SERVER_URL environment variable.

Then restart Claude Desktop/Code to activate the MCP server.

What You Can Do

After setup, you can ask Claude to:

• Generate PlantUML diagrams and get embeddable SVG/PNG URLs
• Create sequence diagrams, class diagrams, architecture diagrams
• Use advanced PlantUML features like !include directives and external libraries
• Encode/decode PlantUML for URL sharing
• Save diagrams locally with secure path restrictions

Saving Diagrams Locally

The generate_plantuml_diagram tool supports saving diagrams to local files via the output_path parameter.

Security: By default, files can only be saved within the current working directory. Only .svg and .png extensions are allowed.

To allow additional directories, set the PLANTUML_ALLOWED_DIRS environment variable:

# Allow specific directories (colon-separated)
PLANTUML_ALLOWED_DIRS=/home/user/diagrams:/tmp/output

# Allow any directory (use with caution)
PLANTUML_ALLOWED_DIRS=*

---

Examples

C4 diagram for plantuml-mcp-server

> add c4 diagram for this project in readme 'C4 diagram for plantuml-mcp-server' section

Sequence diagram for plantuml-mcp-server

> add sequence diagram in readme in architecture section

OAuth2 Authorization Code Flow Diagram

> show me basic oauth2 flow png, open it in browser

---

Development Setup

Prerequisites

• Node.js 18+
• npm

Local Installation

# Clone and setup
git clone https://github.com/mzagar/plantuml-mcp-server.git
cd plantuml-mcp-server
make setup

Development Commands

# Building & Running
make build        # Clean build TypeScript to JavaScript
make dev          # Development mode with watch
make run          # Build and run the server locally

# Testing
make test         # Basic server functionality test
make test-mcp     # Comprehensive testing with mcptools CLI
make test-ci      # Fast CI tests (no external dependencies)

# Setup & Installation  
make install      # Install npm dependencies
make setup        # Full setup (install + build + Claude Code config)
make setup-claude # Show Claude Code MCP configuration instructions

# Release Management
make release-patch  # Create patch release (0.1.0 → 0.1.1)
make release-minor  # Create minor release (0.1.0 → 0.2.0) 
make release-major  # Create major release (0.1.0 → 2.0.0)

# Utilities
make clean        # Clean build directory
make help         # Show all available commands

Environment Variables

Variable	Description	Default
PLANTUML_SERVER_URL	PlantUML server URL	https://www.plantuml.com/plantuml
PLANTUML_ALLOWED_DIRS	Additional directories for output_path (colon-separated, or * for any)	CWD only

License

MIT License - see LICENSE file for details.