README.md•6.7 kB
# PlantUML MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides PlantUML diagram generation capabilities for Claude Desktop and Claude Code.
### Available Tools
1. **`generate_plantuml_diagram`** - Generate diagrams and get embeddable URLs (SVG/PNG)
2. **`encode_plantuml`** - Encode PlantUML code for URL sharing
3. **`decode_plantuml`** - Decode PlantUML from encoded strings
### Available Prompts
1. **`plantuml_error_handling`** - Guidelines for handling PlantUML syntax errors and implementing auto-fix workflows
This prompt provides Claude instances with comprehensive instructions on how to:
- Detect PlantUML syntax errors using native server validation
- Implement intelligent auto-fix workflows for common syntax issues
- Parse structured error responses and apply appropriate corrections
- Handle validation failures gracefully with retry logic
The prompt enables Claude to automatically detect and fix common PlantUML errors like missing tags, invalid arrow syntax, typos in keywords, and missing quotes, making PlantUML diagram generation more reliable and user-friendly.
## Quick Setup
### For Claude Code
```bash
# Using default PlantUML server
claude mcp add plantuml --scope user --env PLANTUML_SERVER_URL=https://www.plantuml.com/plantuml -- npx plantuml-mcp-server
```
### For Claude Desktop
Add this to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"plantuml": {
"command": "npx",
"args": ["plantuml-mcp-server"],
"env": {
"PLANTUML_SERVER_URL": "https://www.plantuml.com/plantuml"
}
}
}
}
```
To use your own PlantUML server, change the `PLANTUML_SERVER_URL` environment variable.
Then restart Claude Desktop/Code to activate the MCP server.
## What You Can Do
After setup, you can ask Claude to:
- **Generate PlantUML diagrams** and get embeddable SVG/PNG URLs
- **Create sequence diagrams, class diagrams, architecture diagrams**
- **Use advanced PlantUML features** like `!include` directives and external libraries
- **Encode/decode PlantUML** for URL sharing
---
## Examples
### C4 diagram for plantuml-mcp-server
```
> add c4 diagram for this project in readme 'C4 diagram for plantuml-mcp-server' section
```
### Sequence diagram for plantuml-mcp-server
```
> add sequence diagram in readme in architecture section
```
### OAuth2 Authorization Code Flow Diagram
```
> show me basic oauth2 flow png, open it in browser
```
---
## Development Setup
### Prerequisites
- Node.js 18+
- npm
### Local Installation
```bash
# Clone and setup
git clone https://github.com/mzagar/plantuml-mcp-server.git
cd plantuml-mcp-server
make setup
```
### Development Commands
```bash
# Building & Running
make build # Clean build TypeScript to JavaScript
make dev # Development mode with watch
make run # Build and run the server locally
# Testing
make test # Basic server functionality test
make test-mcp # Comprehensive testing with mcptools CLI
make test-ci # Fast CI tests (no external dependencies)
# Setup & Installation
make install # Install npm dependencies
make setup # Full setup (install + build + Claude Code config)
make setup-claude # Show Claude Code MCP configuration instructions
# Release Management
make release-patch # Create patch release (0.1.0 → 0.1.1)
make release-minor # Create minor release (0.1.0 → 0.2.0)
make release-major # Create major release (0.1.0 → 2.0.0)
# Utilities
make clean # Clean build directory
make help # Show all available commands
```
### Environment Variables
```bash
# Optional: Use custom PlantUML server
export PLANTUML_SERVER_URL=https://your-server.com/plantuml
# Then run any command
make test-mcp
```
## License
MIT License - see [LICENSE](LICENSE) file for details.