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 ob-file export via signed download URLs (OB_FILE_API_BASE_URL)

• 🔐 Optional OIDC client-credentials flow for ob-file (OB_FILE_OIDC_*)

• 📁 Fallback shared-volume 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

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: client_config_http.json.

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: client_config_sse.json.

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 client_config_stdio.json.

Sample Client Configurations

• client_config_http.json – streamable HTTP (default /mcp)

• client_config_sse.json – SSE + dedicated messagesUrl

• client_config_stdio.json – 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

When OB_FILE_API_BASE_URL is configured, rendered diagrams are uploaded through ob-file and the MCP response returns the signed download_url generated by ob-file. If OB_FILE_OIDC_DISCOVERY_URL, OB_FILE_OIDC_CLIENT_ID, and OB_FILE_OIDC_CLIENT_SECRET are configured, the server obtains and caches an access token automatically via OAuth 2.0 client credentials. The shared-volume path remains as a compatibility fallback for local/dev setups.

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 Dockerfile 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!