plantuml-mcp-server

sysam68/plantuml-mcp-server

3.2

If you are the rightful owner of plantuml-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The PlantUML MCP Server is a Model Context Protocol server that facilitates the generation of PlantUML diagrams for use in Claude Desktop and Claude Code.

Tools
3
Resources
0
Prompts
0

PlantUML MCP Server

Flexible Model Context Protocol (MCP) server that turns PlantUML snippets into shareable diagrams.
All capabilities are exposed over HTTP, Server-Sent Events (SSE), and STDIO, so you can plug the server into Claude Desktop, Flowise, or any other MCP-compatible runtime.

Key Features

  • 🧰 Tools: generate_plantuml_diagram, generate_capability_landscape, generate_business_scenario, encode_plantuml, decode_plantuml
  • 🧾 Prompts: plantuml_error_handling, capability_landscape_input_format, archimate_diagram_input_format, business_scenario_input_format
  • 📚 Static resources: resource://plantuml/server-guide, resource://plantuml/archimate-mapping
  • 🔒 Optional Bearer authentication via MCP_API_KEY
  • ☁️ Optional shared storage export (GENERATED_FILES_DIR + PUBLIC_FILE_BASE_URL)

Requirements

  • Node.js 18+
  • npm 9+
npm install
npm run build     # emits dist/plantuml-mcp-server.js

Use npx plantuml-mcp-server or node dist/plantuml-mcp-server.js once built.

Transport Modes

ModeWhen to useHow to start
HTTP (default)Direct REST-style integration, reverse proxies, health checksMCP_TRANSPORT=http node dist/plantuml-mcp-server.js
SSEClaude Desktop / Flowise over the network with push updatesMCP_TRANSPORT=sse node dist/plantuml-mcp-server.js
STDIOLocal CLI tools (npx, Claude Code CLI, Flowise managed process)MCP_TRANSPORT=stdio npx plantuml-mcp-server

HTTP transport

MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=8765 \
MCP_HTTP_PATH=/mcp \
node dist/plantuml-mcp-server.js
  • POST /mcp to initialize and send JSON-RPC payloads.
  • GET /mcp and DELETE /mcp keep the streamable session alive.
  • GET /healthz is available for readiness probes.
  • Sample client settings: .

SSE transport

MCP_TRANSPORT=sse \
MCP_HOST=0.0.0.0 \
MCP_PORT=8765 \
MCP_SSE_PATH=/sse \
MCP_SSE_MESSAGES_PATH=/messages \
node dist/plantuml-mcp-server.js
  • Clients connect to /sse (GET) for events and POST JSON messages to /messages.
  • Sample config for Claude Desktop / Flowise: .

STDIO transport

MCP_TRANSPORT=stdio npx plantuml-mcp-server
# or run the compiled file directly
MCP_TRANSPORT=stdio node dist/plantuml-mcp-server.js
  • Ideal for local experiments, mcp CLI, or Flowise nodes that spawn the binary.
  • Example setups live in .

Sample Client Configurations

  • – streamable HTTP (default /mcp)
  • – SSE + dedicated messagesUrl
  • – STDIO examples for npx and Flowise-managed processes

Drop these files into your MCP-aware client or copy the snippets as needed. Update hostnames, ports, and API keys to match your deployment.

Environment Variables

VariableDefaultPurpose
LOG_LEVELinfoemergency → debug supported
PLANTUML_SERVER_URLhttps://www.plantuml.com/plantumlUpstream PlantUML renderer
MCP_TRANSPORThttphttp, sse, or stdio
MCP_HOST / MCP_PORT0.0.0.0 / 3000Bind address + port (HTTP/SSE)
MCP_HTTP_PATH/mcpHTTP JSON-RPC endpoint
MCP_HTTP_ENABLE_JSON_RESPONSESfalseReturn JSON body when true (for debugging)
MCP_SSE_PATH/sseSSE stream endpoint
MCP_SSE_MESSAGES_PATH/messagesMessage ingestion endpoint
MCP_API_KEYunsetEnables Bearer auth when provided
GENERATED_FILES_DIR/generated-filesWhere rendered diagrams are persisted
PUBLIC_FILE_BASE_URLhttps://ob-file.fmpn.fr/filesBase URL returned to clients for persisted diagrams
PLANTUML_MCP_SKIP_AUTO_STARTunsetWhen true, skips auto-start so scripts can import the server class without launching transports

Tools, Prompts & Resources

  • Tools are automatically registered through tools/list. They perform validation, optional auto-fixes, and return structured metadata (success, URLs, markdown snippets, encoded diagram data, and validation errors).
  • Prompts guide the model through PlantUML error handling and provide a ready-made capability landscape template.
  • Resource templates expose onboarding content (resource://plantuml/server-guide) so clients can self-discover usage instructions.

Docker Image

The provided builds the TypeScript sources and produces a minimal runtime image:

docker build -t plantuml-mcp-server .
docker run --rm -e MCP_TRANSPORT=http -p 8765:8765 plantuml-mcp-server

Override environment variables (PLANTUML_SERVER_URL, MCP_API_KEY, etc.) as needed.

Testing & Tooling

  • npm run build – compile TypeScript
  • npm start – run using the default HTTP transport
  • npm run start:sse / npm run start:stdio – convenience scripts
  • npm run test:business-scenario – snapshot test that converts test_files/generate_sequence_diagram/payload.json into PlantUML and compares it to expected.puml
  • make test-mcp – smoke-test commands through the mcp CLI

Need Help?

  • Verify connectivity with curl http://<host>:<port>/healthz
  • Confirm auth headers match MCP_API_KEY (Bearer token) if enabled
  • Use the MCP Inspector or Flowise node logs to trace JSON-RPC payloads

The server ships with everything required to operate over HTTP, SSE, and STDIO. Plug in the transport that matches your environment and start generating diagrams!