Skip to main content
Glama
Vlonetatii3

plantuml-mcp

by Vlonetatii3
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

🧩 plantuml-mcp

Servidor MCP (Model Context Protocol) que le da a Claude la capacidad de generar diagramas UML con PlantUML y devolverte la imagen directamente en el chat.

Le pides "hazme un diagrama de secuencia del flujo de un McDonald's" → Claude escribe el código PlantUML → el MCP lo renderiza → ves el diagrama.

Ejemplo: diagrama de secuencia de McDonald's

Código fuente del ejemplo: examples/mcdonalds-secuencia.puml

✨ Qué incluye

Herramienta

Qué hace

render_diagram

Renderiza código PlantUML a PNG (Claude ve la imagen), SVG o TXT (ASCII art). Puede guardarlo en un archivo con output_path. Si hay un error de sintaxis, indica la línea exacta para que Claude lo corrija solo.

get_diagram_urls

Genera enlaces para compartir (PNG/SVG/TXT) y un enlace al editor online de PlantUML.

decode_diagram_url

Recupera el código fuente a partir de una URL de PlantUML.

Funciona con todos los tipos de diagrama de PlantUML: clases, secuencia, casos de uso, actividad, estados, componentes, despliegue, ER, mindmap, Gantt, etc. Si olvidas @startuml / @enduml, se agregan automáticamente.

Related MCP server: UML MCP

📋 Requisitos

  • Node.js 18 o superior

  • Conexión a internet (usa el servidor público de PlantUML, ver Privacidad)

  • No necesitas Java ni instalar PlantUML

🚀 Instalación

git clone https://github.com/Vlonetatii3/PlantUML.git
cd PlantUML
npm install
npm test        # comprueba que todo funciona

Luego configúralo en tu cliente de IA:

Opción A — Claude Code

Solo en este proyecto: el repo ya trae un .mcp.json. Abre Claude Code dentro de la carpeta y acepta el servidor plantuml cuando te lo pregunte.

En todos tus proyectos (recomendado):

claude mcp add plantuml --scope user -- node /ruta/absoluta/a/PlantUML/src/index.js

Comprueba que está conectado con /mcp dentro de Claude Code.

Opción B — Claude Desktop

Edita el archivo de configuración:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "plantuml": {
      "command": "node",
      "args": ["/ruta/absoluta/a/PlantUML/src/index.js"]
    }
  }
}

En Windows usa barras dobles: "C:\\Users\\tu_usuario\\PlantUML\\src\\index.js"

Reinicia Claude Desktop y verás las herramientas en el icono de 🔨.

Opción C — Otros clientes MCP

Cualquier cliente compatible con MCP por stdio (Cursor, VS Code, etc.) sirve: el comando es node /ruta/a/PlantUML/src/index.js.

💬 Ejemplos de uso

Una vez configurado, simplemente pídelo en lenguaje natural:

  • "Hazme un diagrama de clases de un sistema de biblioteca con Libro, Socio y Préstamo"

  • "Diagrama de casos de uso de un cajero automático"

  • "Diagrama de actividad del proceso de inscripción a la universidad"

  • "Diagrama de secuencia del login con JWT y guárdalo en diagramas/login.png"

  • "Pásame el diagrama anterior en ASCII"

🔒 Privacidad

Por defecto los diagramas se renderizan en el servidor público https://www.plantuml.com/plantuml, así que el código de tus diagramas se envía a ese servidor. Para trabajos de clase normalmente no hay problema, pero si trabajas con información sensible puedes usar tu propio servidor con Docker:

docker run -d -p 8080:8080 plantuml/plantuml-server:jetty

Y define la variable de entorno PLANTUML_SERVER:

# Claude Code
claude mcp add plantuml --scope user -e PLANTUML_SERVER=http://localhost:8080 -- node /ruta/a/PlantUML/src/index.js
// Claude Desktop
"plantuml": {
  "command": "node",
  "args": ["/ruta/a/PlantUML/src/index.js"],
  "env": { "PLANTUML_SERVER": "http://localhost:8080" }
}

🛠️ Solución de problemas

Problema

Solución

Claude no ve las herramientas

Reinicia el cliente después de configurarlo. En Claude Code revisa con /mcp.

Cannot find module '@modelcontextprotocol/sdk'

Te faltó npm install dentro de la carpeta del proyecto.

PlantUML server responded 5xx

El servidor público está caído o saturado; reintenta o usa uno propio con Docker.

Diagramas muy grandes fallan

Las URLs tienen límite de tamaño; divide el diagrama o usa un servidor propio.

📁 Estructura

├── src/
│   ├── index.js       # Servidor MCP y definición de herramientas
│   └── plantuml.js    # Codificación PlantUML y llamadas al servidor
├── test/smoke.mjs     # Prueba rápida (npm test)
├── examples/          # Código .puml de ejemplo
├── docs/              # Imágenes del README
└── .mcp.json          # Configuración para Claude Code (alcance de proyecto)

📄 Licencia

MIT — úsalo, modifícalo y compártelo libremente.

Available Tools

3 tools
decode_diagram_urlDecode PlantUML URLB

Recovers the PlantUML source code from a PlantUML server URL or encoded string.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesPlantUML URL (e.g. https://www.plantuml.com/plantuml/png/...) or encoded string

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It identifies the transformation but omits whether it fetches remote URLs, how errors are handled, whether it is idempotent, or if it has side effects. It adds little beyond the purpose statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the action and result with zero filler. It is appropriately sized for a simple decode tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple decode tool with full parameter schema coverage and no output schema, the description covers what it returns ('PlantUML source code') and the input types. It is nearly complete, missing only peripheral behavioral details such as remote-fetch requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'url' parameter is fully described. The description repeats the accepted input types ('PlantUML server URL or encoded string') without adding format details beyond the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Recovers') and resource ('PlantUML source code') with the input scope ('PlantUML server URL or encoded string'). This inherently distinguishes it from render_diagram and get_diagram_urls, which handle rendering and URL retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, prerequisites, or named alternative tool. An agent can infer usage from the purpose, but the description provides no routing information to distinguish this from render_diagram or get_diagram_urls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_diagram_urlsGet PlantUML URLsA

Encodes PlantUML code into shareable PNG/SVG/TXT URLs and an online editor link, without rendering.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesPlantUML source. @startuml/@enduml is added automatically if missing.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It usefully discloses that no rendering occurs and what artifact types come back, but says nothing about failure behavior for invalid PlantUML, URL-length limits for large diagrams, or whether generation is offline/local.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the core action and output types with zero filler. Nothing could be trimmed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, no-output-schema tool, the description covers what is produced (URL variants plus editor link) and that no rendering happens, which is enough to invoke it. It falls just short on error behavior and practical limits of the encoded URL.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and schema description coverage is 100% with the schema already explaining the @startuml/@enduml auto-wrapping. The description adds no additional meaning about the code parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (encodes) and resource (PlantUML code) with the exact artifact produced (shareable PNG/SVG/TXT URLs plus an editor link). The phrase 'without rendering' implicitly separates it from the sibling render_diagram.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'without rendering' hints this is the lighter alternative to render_diagram, but neither sibling is named and there is no explicit when-to-use/when-not statement. An agent can infer the intent but gets no routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

render_diagramRender PlantUML diagramA

Renders PlantUML code (class, sequence, use case, activity, component, state, deployment, ER, mindmap, gantt...) into an image. PNG is returned inline so it can be inspected; SVG/TXT are returned as text. Optionally saves the result to output_path. Reports syntax errors with the offending line.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesPlantUML source. @startuml/@enduml is added automatically if missing.
formatNoOutput format (txt = ASCII art)png
output_pathNoFile path to save the rendered diagram to

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and discloses key traits: PNG is returned inline, SVG/TXT are returned as text, output can be saved to a path, and syntax errors are reported with the offending line. It does not mention rate limits, permissions, or whether saving overwrites an existing file, but covers the primary behaviors well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, then efficiently layers in output behavior, saving, and error reporting. Every sentence adds useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description must explain return behavior and error handling. It does so clearly: inline image vs text output, optional file save, and syntax error reporting. An agent has what it needs to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that PNG is returned inline for inspection while SVG/TXT are returned as text, and that output_path is an optional save location. It adds behavioral context to the format enum rather than just restating it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Renders') and resource ('PlantUML code') and enumerates supported diagram types and output modes. However, it does not explicitly distinguish itself from the sibling tools (get_diagram_urls, decode_diagram_url), so the differentiation remains implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('Renders PlantUML code') and gives a condition for optional saving ('Optionally saves the result to output_path'), but provides no explicit when-to-use guidance or alternatives to the sibling tools. Usage is inferable but not directed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv1.0.0
    • First observeddecode_diagram_url
    • First observedget_diagram_urls
    • First observedrender_diagram
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: rendering to an image, encoding source into shareable URLs, and decoding URLs back to source. There is no meaningful overlap and an agent can unambiguously pick the right one for a given intent.

Naming Consistency4/5

All three follow a verb_noun pattern (render_, get_, decode_ + diagram-related noun), which is readable and predictable. Minor deviation: mixed plural/singular nouns ('diagram_urls' vs 'diagram_url') and three different verbs, but the style is otherwise consistent snake_case.

Tool Count5/5

Three tools is well-scoped for a focused PlantUML utility server covering the render/encode/decode triad. Each tool is justified and there is no redundancy or bloat.

Completeness4/5

The core PlantUML lifecycle (render, generate shareable URL, recover source from URL) is fully covered with no dead ends. Minor gaps exist, such as a standalone validation/syntax-check tool or batch rendering, but render_diagram already reports syntax errors, so agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers