Skip to main content
Glama

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, archimate_macro_reference, capability_landscape_input_format, archimate_diagram_input_format, business_scenario_input_format

  • ๐Ÿ“š Static resources: resource://plantuml/server-guide, resource://plantuml/archimate-mapping

  • ๐Ÿ”’ OIDC/JWKS resource-server authorization for HTTP and SSE

  • โ˜๏ธ Required ob-file export via signed download URLs (OB_FILE_API_BASE_URL)

  • ๐Ÿ” Optional OIDC client-credentials flow for ob-file (OB_FILE_OIDC_*)


Related MCP server: ArchiMate MCP Server

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

Mode

When to use

How to start

HTTP (default)

Direct REST-style integration, reverse proxies, health checks

MCP_TRANSPORT=http node dist/plantuml-mcp-server.js

SSE

Claude Desktop / Flowise over the network with push updates

MCP_TRANSPORT=sse node dist/plantuml-mcp-server.js

STDIO

Local CLI tools

MCP_AUTH_MODE=none MCP_TRANSPORT=stdio npx plantuml-mcp-server

HTTP transport

MCP_TRANSPORT=http \
MCP_AUTH_MODE=oidc \
OIDC_ISSUER_URL=https://your-issuer.example \
OIDC_AUDIENCES=https://mcp-servers.fmpn.fr/plantuml/api/mcp,https://mcp-servers.shared.mpn/plantuml/api/mcp \
MCP_RESOURCE_URL=https://mcp-servers.fmpn.fr/plantuml/api/mcp \
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_AUTH_MODE=oidc \
OIDC_ISSUER_URL=https://your-issuer.example \
OIDC_AUDIENCES=https://mcp-servers.fmpn.fr/plantuml/api/mcp,https://mcp-servers.shared.mpn/plantuml/api/mcp \
MCP_RESOURCE_URL=https://mcp-servers.fmpn.fr/plantuml/api/mcp \
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_AUTH_MODE=none MCP_TRANSPORT=stdio npx plantuml-mcp-server
# or run the compiled file directly
MCP_AUTH_MODE=none 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

Drop these files into your MCP-aware client or copy the snippets as needed. Configure OAuth and hostnames for your deployment.


Environment Variables

Variable

Default

Purpose

LOG_LEVEL

info

emergency โ†’ debug supported

PLANTUML_SERVER_URL

https://www.plantuml.com/plantuml

Upstream PlantUML renderer

MCP_TRANSPORT

http

http, sse, or stdio

MCP_HOST / MCP_PORT

0.0.0.0 / 3000

Bind address + port (HTTP/SSE)

MCP_HTTP_PATH

/mcp

HTTP JSON-RPC endpoint

MCP_HTTP_ENABLE_JSON_RESPONSES

false

Return JSON body when true (for debugging)

MCP_SSE_PATH

/sse

SSE stream endpoint

MCP_SSE_MESSAGES_PATH

/messages

Message ingestion endpoint

MCP_AUTH_MODE

oidc

oidc for network servers; explicit none is restricted to loopback or stdio

OIDC_ISSUER_URL

required

Exact HTTPS issuer used for discovery and token validation

OIDC_AUDIENCES

required

Exact public and internal PlantUML resource URLs, comma-separated

MCP_RESOURCE_URL

required

Canonical HTTPS resource URL advertised in RFC 9728 metadata

MCP_OIDC_ALLOW_INSECURE_LOOPBACK

unset

Test-only: permit HTTP discovery/resource URLs on loopback

OB_FILE_API_BASE_URL

unset

ob-file management API base URL (for example http://ob-file:8000)

OB_FILE_API_TOKEN

unset

Bearer token used to call the ob-file management API

OB_FILE_OIDC_DISCOVERY_URL

unset

Authelia OIDC discovery URL used to obtain a service access token

OB_FILE_OIDC_TOKEN_ENDPOINT

unset

Optional direct token endpoint override (useful for internal service-to-service calls)

OB_FILE_OIDC_CLIENT_ID

unset

OIDC client identifier used by mcp-plantuml

OB_FILE_OIDC_CLIENT_SECRET

unset

OIDC client secret used by mcp-plantuml

OB_FILE_OIDC_SCOPE

obfile:write

Scope requested for the machine upload/public-url flow

OB_FILE_OIDC_AUDIENCE

https://mcp-servers.shared.mpn/obfile/api/mcp

Internal OBFile audience for the separate machine token

OB_FILE_OIDC_FORWARDED_PROTO

unset

Optional X-Forwarded-Proto header for internal Authelia calls

OB_FILE_OIDC_FORWARDED_HOST

unset

Optional X-Forwarded-Host header for internal Authelia calls

MCP_MAX_INLINE_IMAGE_BYTES

2097152

Maximum rendered image size embedded directly in a tool result

EXPOSE_PROMPT_AS_TOOL

false

When true, every MCP prompt is also exposed as an MCP tool with the same name

PLANTUML_MCP_SKIP_AUTO_START

unset

When true, skips auto-start so scripts can import the server class without launching transports

OB_FILE_API_BASE_URL is mandatory for all diagram generation tools. Rendered diagrams are uploaded through ob-file and the MCP response returns only the public diagram_url produced 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. There is no fallback to shared-volume URLs or direct PlantUML URLs.

OIDC requires a signed access token with exact issuer and PlantUML audience, expiration, nonempty jti and human sub, client mcp-dcs-plantuml, and scope plantuml:render. Any authenticated user is accepted regardless of group membership. Each request is checked independently and each session is bound to its subject and client. Discovery must advertise the configured issuer and a same-origin HTTPS JWKS endpoint. RFC 9728 metadata is served under /.well-known/oauth-protected-resource followed by the canonical resource path. The OAuth client uses authorization code with PKCE and the standard claims policy configured by OB-SEC; its Codex and Claude callbacks are registered there.

For isolated local tests, set MCP_AUTH_MODE=none MCP_HOST=127.0.0.1; this bypass is rejected on non-loopback network binds. STDIO also requires explicit MCP_AUTH_MODE=none. Never expose this mode through a proxy. MCP_API_KEY no longer authenticates incoming requests. In OIDC mode, OBFile calls require the separate mcp-plantuml client-credentials identity, the OBFile audience and obfile:write; the incoming human token is never forwarded. The legacy OB_FILE_API_TOKEN fallback is available only in local mode.


Tools, Prompts & Resources

  • Tools are automatically registered through tools/list. They perform validation and optional auto-fixes, persist rendered diagrams through ob-file, and return structured metadata plus native MCP PNG image content up to the configured inline-size limit. SVG requests keep their public SVG URL and include a PNG preview for host compatibility.

  • Diagram generation tools require ob-file and expose only the public diagram_url and markdown_embed; internal PlantUML URLs and storage metadata are not returned.

  • encode_plantuml returns only the encoded payload and no longer exposes direct PlantUML render URLs.

  • Prompts guide the model through PlantUML error handling and provide a ready-made capability landscape template.

  • archimate_macro_reference is loaded from documentation/archimate_macro_reference.md, so the reference can evolve without code changes.

  • For ArchiMate, the official PlantUML stdlib defines the macros (Business_Service, Motivation_Principle, Grouping, Rel_Serving, etc.), while fields such as code, note, description, extra, raw, layout, format, legend_type, and use_local_stdlib are extensions added by mcp-plantuml.

  • When EXPOSE_PROMPT_AS_TOOL=true, every prompt is mirrored as a tool for MCP clients that do not consume prompts.

  • 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 --env-file /path/to/oidc.env -p 8765:3000 plantuml-mcp-server

Provide the OIDC settings above through the environment file.


Testing & Tooling

  • npm run build โ€“ compile TypeScript

  • npm run test:auth โ€“ signed-token and Streamable HTTP authorization contract tests with local fixtures

  • 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

  • Check the issuer, audience, client, group, scope, and protected-resource metadata when a bearer token is rejected

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

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers