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