PlantUML MCP Server

A Model Context Protocol (MCP) server that wraps PlantUML functionality, allowing AI assistants to generate UML diagrams from text descriptions.

Features

• Generate Diagrams: Create diagrams in multiple formats (PNG, SVG, TXT, PDF, etc.)

• Syntax Checking: Validate PlantUML syntax without generating images

• Source Extraction: Extract PlantUML source from PNG/SVG metadata

• Dark Mode Support: Generate diagrams with dark theme

• Version Info: Get PlantUML and Java version information

Prerequisites

• Node.js 18 or higher

• Java Runtime Environment (JRE)

• PlantUML JAR file

Installation

1. Clone this repository:

git clone <repository-url>
cd planuml

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Set the PlantUML JAR path (optional):

export PLANTUML_JAR=/path/to/plantuml.jar

Default path: /Users/userxxx/bin/plantuml.jar

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "plantuml": {
      "command": "node",
      "args": ["xxx/dist/index.js"],
      "env": {
        "PLANTUML_JAR": "xxx/plantuml.jar"
      }
    }
  }
}

Available Tools

1. generate_diagram

Generate a diagram from PlantUML source code.

Parameters:

• source (required): PlantUML source code

• format (optional): Output format - png, svg, txt, utxt, eps, latex, pdf (default: png)

• darkMode (optional): Render in dark mode (default: false)

Returns: Base64-encoded diagram data

Example:

{
  "source": "@startuml\nAlice -> Bob: Hello\n@enduml",
  "format": "svg",
  "darkMode": false
}

2. check_syntax

Check PlantUML diagram syntax without generating images.

Parameters:

• source (required): PlantUML source code to validate

Returns: Validation result or syntax errors

Example:

{
  "source": "@startuml\nAlice -> Bob: Hello\n@enduml"
}

3. extract_source

Extract embedded PlantUML source from PNG or SVG metadata.

Parameters:

• filePath (required): Path to the PNG or SVG file

Returns: Extracted PlantUML source code

Example:

{
  "filePath": "/path/to/diagram.png"
}

4. get_plantuml_version

Get PlantUML and Java version information.

Parameters: None

Returns: Version information

PlantUML Syntax Examples

Sequence Diagram

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml

Class Diagram

@startuml
class User {
  +String name
  +String email
  +login()
  +logout()
}

class Admin {
  +manageUsers()
}

User <|-- Admin
@enduml

Activity Diagram

@startuml
start
:Initialize;
if (Check condition?) then (yes)
  :Process A;
else (no)
  :Process B;
endif
stop
@enduml

Use Case Diagram

@startuml
left to right direction
actor User
actor Admin

rectangle System {
  User -- (Login)
  User -- (View Profile)
  Admin -- (Manage Users)
  Admin -- (View Reports)
}
@enduml

Development

Build

npm run build

Watch mode

npm run watch

Environment Variables

• PLANTUML_JAR: Path to the PlantUML JAR file (default: /Users/userxxx/bin/plantuml.jar)

Supported Output Formats

• png: PNG images (default)

• svg: SVG vector graphics

• txt: ASCII art diagrams

• utxt: ASCII art with Unicode characters

• eps: Encapsulated PostScript

• latex: LaTeX/TikZ output

• pdf: PDF documents

Error Handling

The server handles various error scenarios:

• Invalid PlantUML syntax

• Missing PlantUML JAR file

• Java runtime errors

• File I/O errors

Errors are returned with descriptive messages to help diagnose issues.

License

MIT

Resources

• PlantUML Official Documentation

• Model Context Protocol

• PlantUML Language Reference