Skip to main content
Glama

PlantUML MCP Server

LightNow capabilities

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.

Related MCP server: UMLmcp

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

C4 Container Diagram - PlantUML MCP Server

Sequence diagram for plantuml-mcp-server

> add sequence diagram in readme in architecture section

PlantUML MCP Server Architecture

OAuth2 Authorization Code Flow Diagram

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

OAuth2 Authorization Code Flow


Development Setup

Prerequisites

  • Node.js 22.12.0 or later

  • npm

Local Installation

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

Development Commands

# Show all available commands
make help

# Build and run all tests
make clean build test-all

Local MCP Smoke Test

Test the compiled server in this checkout through mcpc:

Requires Node.js 22.12.0 or later, npm, Make, and network access.

# Install project dependencies, then build and test the local server
npm ci --ignore-scripts --no-audit --no-fund --engine-strict
make test-mcpc

If mcpc is missing from PATH, the target installs the official Apify CLI with npm install --global --no-audit --no-fund @apify/mcpc. It reuses an existing installation without upgrading it and checks mcpc --version before testing. The smoke test has been verified with mcpc 0.6.0.

This is a global CLI installation, not a project dependency. It requires permission to write to the npm global prefix. The target never uses sudo. If installation fails or the CLI is still not on PATH, the test stops with instructions. You can also install it manually with npm install -g @apify/mcpc.

make test-mcp is an alias. make test-all runs the unit/type checks and this MCP test, including the CLI installation check. Running node scripts/test-mcpc.mjs directly does not install the CLI.

The test verifies all three tools, the prompt, Unicode roundtrip, diagram URLs, SVG/PNG files, C4 rendering, syntax errors, and output-path restrictions.

It always renders synthetic diagrams through https://www.plantuml.com/plantuml, so network access is required. It does not use a published npm server or an existing user session.

The runner creates its own temporary config, private MCPC_HOME_DIR, working directory, and output directory. Its @local session is isolated from user sessions and closed after success, failure, or interruption. It retains images and results.json in the artifact directory printed by the command.

Success ends with PASS local mcpc smoke test and exit code 0. Missing prerequisites, network errors, failed assertions, or cleanup failures return a nonzero exit code.

For a trusted corporate CA, run:

NODE_EXTRA_CA_CERTS=/absolute/path/to/trusted-ca.pem make test-mcpc

The runner forwards this setting to the server. Do not disable TLS validation. If cleanup fails, use its printed private home: MCPC_HOME_DIR="<artifact-directory>/mcpc" mcpc close @local. Do not close sessions in your default mcpc home.

Agent instructions are in AGENTS.md.

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.

MCP Registry Listings

Available Tools

3 tools
decode_plantumlA

Decode encoded PlantUML string back to PlantUML code

Inputs: encoded_string (required).

encode_plantumlB

Encode PlantUML code for URL usage

Inputs: plantuml_code (required).

generate_plantuml_diagramA

Generate a PlantUML diagram with automatic syntax validation and error reporting for auto-fix workflows. Returns embeddable image URLs for valid diagrams or structured error details for invalid syntax that can be automatically corrected. Optionally saves the diagram to a local file.

Inputs: plantuml_code (required), format, output_path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: decode_plantuml reverses encoding, encode_plantuml prepares code for URLs, and generate_plantuml_diagram creates diagrams with validation. There is no overlap or ambiguity between these functions, making tool selection straightforward for an agent.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (decode_plantuml, encode_plantuml, generate_plantuml_diagram). The naming is predictable and readable, adhering to a uniform style throughout the set.

    Tool Count5/5

    With 3 tools, this server is well-scoped for handling PlantUML encoding, decoding, and diagram generation. Each tool earns its place by covering essential operations without bloat, making the count appropriate for the domain.

    Completeness5/5

    The tool set provides complete coverage for core PlantUML workflows: encoding for URLs, decoding back to code, and generating diagrams with validation and error handling. There are no obvious gaps, as these tools support the full lifecycle from code to visual output.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to generate UML diagrams through natural language by rendering PlantUML code into PNG or SVG images. Supports sequence diagrams, class diagrams, use case diagrams, and other UML chart types with Base64-encoded output.
      7
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to generate PlantUML code for UML Class and Sequence diagrams using Google Gemini AI. Supports both domain JSON input and free text descriptions to create structured UML diagrams.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables generating cloud architecture diagrams, flowcharts, sequence diagrams, and more using three rendering engines: mingrammer/diagrams, Mermaid, and PlantUML.
      56 PyPI
      3
      MIT